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Foreword 



The C language under CP/M-68K™ is easy to read, easy to maintain, and highly 
portable. CP/M-68K can run most applications written in C for the UNIX® operating 
system, except programs that use the UNIX fork/exec multitasking primitives or that 
read UNIX file structures. 

The C Language Programming Guide for CP/M-68K is not a tutorial. This manual 
describes how to program in C under the CP/M-68K operating system, and is best used 
by programmers familiar with the C language as described in The C Programming 
Language (Kernighan and Ritchie, 1978). 

The commonly accepted standard for C language programming is the Portable C 
Compiler (PCC), written by Stephen C. Johnson. Many versions of the UNIX operating 
system use PCC, including the Zilog®, ONYX™, Xenix®, Berkeley UNIX, and UNIQ™ 
systems. 

The CP/M-68K C compiler differs from PCC on the following points: 

■ The CP/M-68K C int (default) data type is 16 bits long. Pointers are 32 bits long. 
All function definitions and function calls that use long (32-bit ints) and pointer 
parameters must use the proper declarations. 

■ long, int, and char register variables are assigned to D registers. Five such registers 
are available in each procedure. 

■ Any register variable used as a pointer is assigned to an A register. There are 
three such registers available in each procedure. 

■ All local declarations in a function body must precede the first executable 
statement of the function. 

■ The CP/M-68K C compiler handles structure initialization as if the structure 
were an array of short integers, as in UNIX version 6. 

n The first eight characters of variable and function names must be unique. The 
first seven characters of external names must be unique. 

■ The CP/M-68K C compiler does not support floating point. 

■ The CP/M-68K C compiler does not support structure assignment, structure 
arguments, and structures returned from procedures. 

■ The CP/M-68K C compiler does not support initialization of automatic variables. 

■ The CP/M-68K C compiler does not support enumeration types. 



Section 1 of this manual describes the conventions of using C language under 
CP/M-68K. Section 2 discusses C language compatibility with UNIX version 7 and 
provides a dictionary of C library routines for CP/M-68K. Section 3 presents a style 
guide for coding C language programs. 

Appendix A is a table of CP/M-68K error codes. Appendix B discusses compiler 
components, tells you how to operate the compiler, and suggests ways to conserve the 
disk space used for compiling. Appendix C presents sample C modules that are written 
and documented according to the style conventions outlined in Section 3. 
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Section 1 
Using C Language Under CP/M-68K 

1.1 Compiling a CP/M-68K C Program 

To compile a C program under CP/M-68K, use the c.sub and clink.sub command 
files. You can separately compile files with these commands. You must type the com- 
mands as shown in the command line. To invoke the compiler, use the following 
command form: 

[submit] c file 

where file.c is the filename. The submit command is optional. The compiler produces 
file.o as the object. To invoke the linker, use the following command form: 

[submit] clink file 

The command file automatically includes all libraries and header files. You can specify 
multiple files. For example, the following commands compile and link files a.c, b.c, 
and c.c: 

A > submit c a 
A > submit c b 
A > submit c c 
A > submit c 1 i nK a b c 

The output goes to file A.68K. 

1.2 Memory Layout 

The memory layouts of C programs in CP/M-68K are similar to those of UNIX C 
programs. The program comprises three segments: text instructions, initialized data, 
and BSS, which is uninitialized data. Automatic variables are allocated on the stack. 
These segments are arranged in memory as illustrated in Figure 1-1. 
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STACK (GROWS TO LOWER ADDRESSES) 



HEAP (GROWS TO HIGHER ADDRESSES) 



BLOCK STORAGE SEGMENT 



DATA SEGMENT 



TEXT SEGMENT 



TPAHIGH 



BREAK 
END 
EDATA 
ETEXT 

TPA LOW 



Figure 1-1. Memory Layout 



There are two dynamic memory areas: the stack and the heap. Procedure calls and 
automatic variables use the stack. The brk, sbrk, malloc, and free procedures manage 
the heap. Dynamically growing data structures, such as symbol tables, use the heap. 

The linkage editor defines the locations etext, edata, and end. The locations determine 
the ending addresses of the text, data, and BSS segments. The break location is the first 
free location following the heap area. 



1.3 Calling Conventions 

The jump to subroutine (JSR) instruction calls procedures in C. Register A6 acts as 
the frame pointer for referencing local storage. Arguments are pushed in reverse order 
onto the A7 stack. Word and character arguments to functions occupy 16 bits on the 
stack. Long and pointer arguments occupy 32 bits. The function value return register is 
always DO. Functions that declare no return value return an undefined value. 
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For example, the following sequence 

x y 2 ( ) i 

1 o n S a 5 

i n t b 5 

char x 5 

register y 5 



b = blivot(x»a)5 



generates the following code: 



. x y 2 : 



link a 6 » # - 8 * Space for aibtx 

m o v e m ♦ 1 d G - d 7 t - ( a 7 ) * d 7 used for y 

. *d6 reserves space 



move.l - 4 ( a 6 ) > ( a 7 ) * Load parameter a 

m o v e ♦ b - 8 ( a G ) * d * L o a d p a r a m e t e r x 

e x t ♦ w dO # Extend to word size 

m o v e ♦ w d » - ( a 7 ) * P u s h i t 

J s r _ b 1 i v o t * Call subroutine 

add«l #2>a7 * Pop a r Sum en t list 

m o v e ♦ w d » - G ( a G ) * Store return parameter 

tst»l (a7)+ * Purse Ion Sword 

m o v e m ♦ 1 ( a 7 ) + > d 7 * Unsave reSisters 

u n 1 K a 6 * Restore frame pointer 

rts * Return to caller 
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C code, in which all arguments are the same length, might not work without 
modification because of the varying length of arguments on the stack. 

The compiler adds an underline character, _, to the beginning of each external variable 
or function name. This means that all external names in C must be unique in seven 
characters. 

The compiler-generated code maintains a long word at the top of the stack for use 
in subroutine calls. This shortens the stack-popping code required on return from a 
procedure call. The movem.l instruction, which saves the registers, contains an extra 
register to allocate this space. 

The compiler uses registers D3 through D7, and A3 through A5, for register variables. 
A procedure called from a C program must save and restore these registers, if they are 
used. The compiler-generated code saves only those registers used. Registers DO through 
D2, and AO through A2, are scratch registers and can be modified by the called procedure. 



1.4 Stack Frame 

Figure 1-2 illustrates the standard C stack frame. 



A/ — 


► 


LONGWORD FOR PROCEDURE CALLS 




SAVED REGISTERS 




LOCAL VARIABLE AREA 


Afi 


PREVIOUS VALUE OF A6 








RETURN ADDRESS 




ARGUMENT 1 




ARGUMENT 2 







Figure 1-2. C Stack Frame 
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Arguments are either 2 or 4 bytes, depending on argument type. The compiler- 
generated code uses A6 to reference all variables on the stack. 

1.5 Command Line Interface 

The standard C argc/argv interface for arguments typed on the command line also 
works under CP/M-68K. For example, the command form 

command argl arg2 arg3 ... argn 

causes the following interface setup: 

argc = n + 1 

argv[0] — > "C Runtime" 

argv[l] — > "argl" 

argv[2] — > «arg2" 



argv[n] — > argn 

You cannot obtain the command name under CP/M-68K. Therefore, the argv[0] argu- 
ment is always incorrect. 



1.6 I/O Conventions 

UNIX C programs use two types of file and device I/O: regular files and stream files. 
A unique number, called a file descriptor, identifies regular files. In CP/M-68K, this 
number is in the range to 15. The address of a user control block in the run-time system 
identifies stream files. Unlike regular files, stream files use some form of intermediate 
buffering, making single-byte I/O more efficient. 

Under UNIX, you can reference peripheral devices, such as terminals and printers, 
as files, using the special names /dev/tty for terminal and /dev/lp for printer. Under 
CP/M-68K, CON: is for the console device, and LST: is for the listing device. 
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CP/M-68K stores ASCII files with a carriage return line-feed after each line. A CTRL-Z 
(Oxla) character indicates end-of-file. C programs usually end lines with only a line-feed. 
This means that in CP/M-68K C, read and write operations to ASCII files must insert 
and delete carriage-return characters. The CTRL-Z must be deleted on read and inserted 
on close for such files. These operations are not desirable for binary files. CP/M-68K C 
includes an extra entry point to all file open and creat calls to distinguish between ASCII 
and binary files. 



1.7 Standard Files 

C programs begin execution with three files already open: the standard input, standard 
output, and standard error files. You can access these files as either stream or regular 
files in the C program. The following definitions are available from the <stdio.h> file: 



Table 1-1. Standard File Definitions 



File 



File Descriptor 



Stream Name 



standard input 
standard output 
standard error 



STDIN 

STDOUT 

STDERR 



stdin 

stdout 

stderr 



The usual library routines close and reopen these standard files. In addition, you can 
redirect I/O from the command line. 
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1.8 I/O Redirection 

You can redirect the C program standard I/O with the < and > characters. No space 
is allowed between the < or > and the filename. You cannot redirect the standard error file. 

For example, the command 
test < a > 1 s t : c d e f 

executes the file test.68K, with the standard input coming from disk file a and the 
standard output going to the listing device. The argument list is c d e f. 

End of Section 1 
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Section 2 
C Language Library Routines 



The CP/M-68K C library is a collection of routines for I/O, dynamic memory 
allocation, system traps, and data conversion. 



2.1 Compatibility with UNIX V7 

The C library is compatible with UNIX version 7, allowing programs to move easily 
from UNIX to CP/M-68K. CP/M-68K C simulates many UNIX operating system calls 
and features. However, CP/M-68K does not support the following C functions that 
UNIX implements: 

■ the fork/exec, kill, lock, nice, pause, ptrace, sync, and wait primitives 

■ the acct system call 

■ the alarm function, or the stime, time, ftime, and times system calls 

■ the dup and dup2 duplicate file descriptor functions 

■ the getuid, getgid, geteuid, getegid, setuid, and setgid functions 

■ the indir indirect system call 

■ the ioctl, stty, and gtty system calls 

■ the link system call 

■ the chdir, chroot, mknod, mount, umount, mpx, pipe, pkon, pkoff, profil, sync, 
stat, fstat, umask, and utime system calls 

■ the phys system call 
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The following UNIX library functions are not available under CP/M-68K: 

■ Assert 

■ Crypt 

■ DBM 

■ Getenv 

■ Getgrent, getlogin, getpw, and getpwent functions 

■ 13tol, ltoB 

■ monitor 

■ itom, madd, msub, mult, mdiv, min, mout, pow, gcd, and rpow 

■ nlist 

■ pkopen, pkclose, pkread, pkwrite, and pkfail 

■ plot 

■ popen, pclose 

■ sleep 

■ system 

■ ttyslot 

The CP/M-68K C language library does not contain the floating-point routines 
available under UNIX. 

Entry points have been added to file open and creat calls to distinguish between ASCII 
and binary files. Byte level end-of-file is unavailable for binary files. ASCII files, however, 
are compatible with UNIX, and with the CP/M-68K text editors and utilities that use 
ASCII files. 

The C Programming Guide for CP/M-68K does not separate the UNIX system calls 
and library functions; all calls are library functions under CP/M-68K. 



2.2 Library Functions under CP/M-68K 

The remainder of this section lists alphabetically the library routines that C supports 
under CP/M-68K. The C compiler accepts entry in both upper- and lower-case; however, 
you must, type all library routines in lower-case, as shown in the calling sequences. 
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The abort Function 

The abort function terminates the current program with an error. The error is system 
dependent. The 68000 uses an illegal instruction trap. This invokes DDT-68K™, if the 
debugger is loaded with the object program. 

Calling Sequence: 

WORD code; 

abort(code); 
Arguments: 

code loads into register DO before abort 

Returns: 

The abort function never returns. 
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The abs Function 



The abs function takes the absolute value of a single argument. This function is 
implemented as a macro in <stdio.h>; arguments with side effects do not work as you 
expect. For example, the call 

a = abs(*x + +); 

increments x twice. 

Calling Sequence: 

WORD val; 
WORD ret; 

ret = abs(val); 
Arguments: 

val 
Returns: 

ret the absolute value of val 



the input value 



2-4 
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The access Function 



The access function checks whether the invoking program can legally access a file. 
Under CP/M-68K, the file is accessible if it exists. 

Calling Sequence: 



BYTE *name; 
WORD mode; 
WORD ret; 

ret = access(name,mode); 

Arguments: 



name 



mode 



points to the null-terminated filename 

4 to check read access 

2 to check write access 

1 to check exec access 

to check directory path access (CP/M-68K ignores this argument) 



Returns: 



access allowed 
access not allowed 



Note: 



CP/M-68K checks only to see if the file exists. 
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The atoi, atol Functions 

The atoi and atol functions convert an ASCII string to an integer or long binary 
number, respectively. Strings converted by atoi and atol have the following format: 

[...][-][ + ]dddddd.... 

The functions ignore leading spaces and permit one leading sign. 

Calling Sequence: 

BYTE * string; 
WORD ival; 
LONG lval,atol(); 

ival = atoi(string); 
lval = atol (string); 

Arguments: 



atol is not a default value and must be declared. String is a null-terminated string 
containing the number to be converted. Conversion proceeds until the digits are 
exhausted. Zero returns if no digits remain. 

Returns: 

Converted value as ival (int), or lval (long). 

Note: 

The atoi and atol functions do not detect or report overflow. You cannot limit the 
number of contiguous digits processed or determine the number of digits actually 
processed. 
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The brk, sbrk Functions 



The brk and sbrk functions extend the heap portion of the user program. The brk 
function sets the upper bound of the program, called the break in UNIX terminology, 
to an absolute address. The sbrk function extends the program by an incremental 
amount. 

Calling Sequence: 

WORD brk(); 

BYTE *addr,*sbrk(); 

WORD ret; 

BYTE * start; 

ret = brk(addr); 
start = sbrk(incr) 

Arguments: 

addr the desired new break address 

incr the incremental number of bytes desired 

Returns: 



success (brk) 
failure (brk) 



start begins the allocated area (sbrk) 

failure (sbrk) 
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The calloc, malloc, realloc, free Functions 

The calloc, malloc, realloc, and free functions manage the dynamic area between the 
region and the stack. 

The malloc function allocates an area of contiguous bytes aligned on a word boundary 
and returns the address of this area, malloc uses the sbrk function to allocate additional 
heap space, if necessary. 

The calloc function allocates space for an array of elements, whose size is given 
in bytes. 

The realloc function changes the size of a block. The address of the block returns. 

The free function releases a block previously allocated by malloc. 

Calling Sequence: 

WORD size,number; 

BYTE *addr,*malloc(),*calloc(),*realloc(); 

addr = malloc(size); 
addr = calloc(number,size); 
addr = realloc(addr,size); 
free (addr); 

Arguments: 

size the number of bytes desired 

number the number of elements desired 

addr points to the allocated region 

Returns: 

Address of the allocated region if successful, if unsuccessful. 
Note: 

Freeing a bogus address can be disastrous. 
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The chmod, chown Functions 



Under UNIX, the chmod and chown system calls allow you to change the protection 
and owner ID of an existing file. CP/M-68K treats these calls as NO-OPS if the file exists. 

Calling Sequence: 

BYTE *name; 

WORD mode,owner,group,ret; 

ret = chmod(name,mode); 

ret = chown(name,owner,group); 



Arguments: 

name 
mode 
owner 
group 

Returns: 

ret 



the affected filename (null-terminated) 
the new mode for the file 
the new owner of the file 
the new group number 



if the file exists 
-1 if the file does not exist 
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The close Function 



The close function terminates access to a file or device. This routine acts on files 
opened with the open or creat functions. Specify a file descriptor, not a stream, for the 
operation. The fclose function closes stream files. 

Calling Sequence: 

WORD fd,ret; 

ret = close(fd); 
Arguments: 



fd 
Returns: 



the file descriptor to be closed 



successful close 
unknown file descriptor 



2-10 
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The creat, creata, creatb Functions 



The creat function adds a new file to a disk directory. The file can then be referenced 
by the file descriptor, but not as a stream file. The creat and creata functions create an 
ASCII file. The creatb function creates a binary file. 

Calling Sequence: 

BYTE *name; 
WORD mode,fd; 

fd = creat(name,mode); 
fd = creata(name,mode); 
fd = creatb(name,mode); 

Arguments: 

name the filename string, null-terminated 

mode the UNIX file mode, ignored by CP/M-68K 

Returns: 



fd 



The file descriptor for the opened file. A file descriptor is an int 
quantity that denotes an open file in a read, write or lseek call. 



Note: 



Returned if there are any errors. 



UNIX programs that use binary files compile successfully, but execute improperly. 
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The ctype Functions 



The file <ctype.h> defines a number of functions that classify ASCII characters. These 
functions indicate whether a character belongs to a certain character class, returning 
nonzero for true and zero for false. The following table defines ctype functions. 



Table 2-1. ctype Functions 



Function 



Meaning 



isalpha(c) c is a letter. 

isupper(c) c is upper-case. 

islower(c) c is lower-case. 

isdigit(c) c is a digit. 

isalnum(c) c is alphanumeric. 

isspace(c) c is a white space character. 

ispunct(c) c is a punctuation character. 

isprint(c) c is a printable character. 

iscntrl(c) c is a control character. 

isascii(c) c is an ASCII character (< 0x80). 



The white space characters are the space (0x20), tab (0x09), carriage return (OxOd), 
line-feed (0x0a), and form-feed (0x0c) characters. Punctuation characters are not control 
or alphanumeric characters. The printing characters are the space (0x20) through the 
tilde (0x7e). A control character is less than a space (0x20). 
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Calling Sequence: 



#include <ctype.h> 


WORD ret; 


BYTE c; /* or WORD c; */ 


ret = 


isalpha(c); 


ret = 


isupper(c); 


ret = 


islower(c); 


ret = 


isdigit(c); 


ret = 


isalnum(c); 


ret = 


isspace(c); 


ret = 


ispunct(c); 


ret = 


isprint(c); 


ret = 


iscntrl(c); 


ret = 


isascii(c); 


Arguments: 



the character to be classified 



Returns: 



ret 


= for false 


ret 


<>0 for true 


Note: 





These functions are implemented as macros; arguments with side effects, such as 
*p + + , work incorrectly in some cases. Bogus values return if arguments are not 
ASCII characters. For example, >0x7f. 
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The end, etext, edata Locations 

The linkage editor defines the labels end, etext, and edata as the first location past 
the BSS, text, and data regions, respectively. The program-break location, which is the 
last used location, is initially set to end. However, many library functions alter this 
location. sbrk(O) can retrieve the break. 
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The exit, _exit Functions 

The exit function passes control to CP/M-68K. An optional completion code, which 
CP/M-68K ignores, might return, exit deallocates all memory and closes any open files, 
exit also flushes the buffer for stream output files. 

The _exit function immediately returns control to CP/M-68K, without flushing or 
closing open files. 

Calling Sequence: 

WORD code; 

exit(code); 
_exit(code); 

Arguments: 

code optional return code 

Returns: 



no returns. 
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The fclose, fflush Functions 
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The fclose and fflush functions close and flush stream files. The stream address 
identifies the stream to be closed. 

Calling Sequence: 

WORD ret; 
FILE * stream; 

ret = fclose(stream); 
. ret = fflush(stream); 

Arguments: 



stream 


the stream address 


Returns: 







successful 


-1 


bad stream address or write failure 
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The feof, ferror, clearerr, fileno Functions 



The feof, ferror, clearerr, fileno Functions 

These functions manipulate file streams in a system-independent manner. 

The feof function returns nonzero if a specified stream is at end-of-file, and zero if it 
is not. 

The ferror function returns nonzero when an error has occurred on a specified stream. 
The clearerr function clears this error. This is useful for functions such as putw, where 
no error indication returns for output failures. 

The fileno function returns the file descriptor associated with an open stream. 

Calling Sequence: 

WORD ret; 
FILE * stream; 
WORD fd; 

ret = feof (stream); 
ret = ferror (stream); 
clearerr (stream); 
fd = fileno(stream); 



Arguments: 

stream 

Returns: 

ret 
fd 



the stream address 



a zero or nonzero indicator 
the returned file descriptor 
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The fopen, freopen, fdopen Functions 

The fopen, freopen, and fdopen functions associate an I/O stream with a file or device. 

The fopen and fopena functions open an existing ASCII file for I/O as a stream. The 
fopenb function opens an existing binary file for I/O as a stream. 

The freopen and freopa functions substitute a new ASCII file for an open stream. The 
freopb function substitutes a new binary file for an open stream. 

The fdopen function associates a file that file descriptor opened, using open or creat, 
with a stream. 

Calling Sequence: 

FILE *fopen(),fopena(),fopenb(); 
FILE *freopen(),freopa(),freopb(); 
FILE *fdopen(); 
FILE * stream; 
BYTE *name,* access; 
WORD fd; 

stream = fopen(name,access); 

stream = fopena(name,access); 

stream = fopenb (name,access); 

stream = freopen(name,access,stream); • 

stream = freopa(name,access,stream); 

stream = freopb (name,access,stream); 

stream = fdopen(fd,access); 
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The fopen, freopen, fdopen Functions 



Arguments: 




name 
stream 


the null-terminated filename string 
the stream address 


access 


the access string: 




r read the file 
w write the file 
a append to a file 


Returns: 




stream 



successful if stream address open 
unsuccessful 


Note: 





UNIX programs that use fopen on binary files ^compile and link correctly, but 
execute improperly. 
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The fread, fwrite Functions 



The fread and fwrite functions transfer a stream of bytes between a stream file and 
primary memory. 



Calling Sequence: 

WORD nitems; 

BYTE *buff; 

WORD size; 

FILE * stream; 

nitems = fread(buff,size,nitems,stream); 
nitems = fwrite(buff,size,nitems,stream); 



Arguments: 



buff 
size 
nitems 
stream 



the primary memory buffer address 
the number of bytes in each item 
the number of items to transfer 
an open stream file 



Returns: 



nitems the number of items read or written 

error, including EOF 
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The fseek, ftell, rewind Functions 

The fseek, ftell, and rewind functions position a stream file. 

The fseek function sets the read or write pointer to an arbitrary offset in the stream. 
The rewind function sets the read or write pointer to the beginning of the stream. These 
calls have no effect on the console device or the listing device. 

The ftell function returns the present value of the read or write pointer in the stream. 
This call returns a meaningless value for nonfile devices. 

Calling Sequence: 

WORD ret; 
FILE * stream; 
LONG offset,ftell(); 
WORD ptrname; 

ret = fseek(stream,offset,ptrname); 
ret = rewind(stream); 
offset = ftell (stream); 

Arguments: 



stream 

offset 

ptrname 


the stream address 

a signed offset measured in b 

the interpretation of offset: 




= > from beginning of file 

1 = > from current position 

2 = > from end of file 


Returns: 




ret 
offset 


for success, -1 for failure 
present offset in stream 


Note: 





ASCII file seek and tell operations do not account for carriage returns that are 
eventually deleted. CTRL-Z characters at the end of the file are correctly handled. 
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The getc, getchar, fgetc, getw, getl Functions 

The getc, getchar, fgetc, getw, and getl functions perform input from a stream. 

The getc function reads a single character from an input stream. This function is 
implemented as a macro in <stdio.h>, and arguments should not have side effects. 

The getchar function reads a single character from the standard input. It is identical 
to getc(stdin) in all respects. 



The fgetc function is a function implementation of getc, used to reduce object code 



size. 



The getw function reads a 16-bit word from the stream, high byte first. This is 
compatible with the read function call. No special alignment is required. 

The getl function reads a 32-bit long from the stream, in 68000 byte order. No special 
alignment is required. 

Calling Sequence: 

WORD ichar; 
FILE * stream; 
WORD iword; 
LONG ilong,getl(); 

ichar = getc(stream); 
ichar = getchar (); 
ichar = fgetc(stream); 
iword = getw(stream); 
ilong = getl (stream); 
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The getc, getchar, fgetc, getw, getl Functions 



Arguments: 



stream the stream address 



Returns: 



ichar character read from stream 

iword word read from stream 

ilong longword read from stream 

-1 on read failures 



Note: 



Error return from getchar is incompatible with UNIX prior to version 7. Error 
return from getl or getw is a valid value that might occur in the file normally. Use 
feof or ferror to detect end-of-file or read errors. 
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The getpass Function 

The getpass function reads a password from the console device. A prompt is output, 
and the input read without echoing to the console. A pointer returns to a 0- to 8 -character 
null-terminated string. 

Calling Sequence: 



BYTE 
BYTE 
BYTE 


* prompt; 

* getpass; 
*pass; 


pass = 


getpass (prompt); 


Arguments: 




prompt 


a null-terminated prompt string 


Returns: 




pass 


points to the password read 


Note: 





The return value points to static data whose content is overwritten by each call. 
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The getpid Function 

The getpid function is a bogus routine that returns a false process ID. This routine is 
strictly for UNIX compatibility; serves no purpose under CP/M-68K. The return value 
is unpredictable in some implementations. 

Calling Sequence: 

WORD pid; 

pid = getpid(); 
Arguments: 

no arguments. 
Returns: 

pid false process ID 
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The gets, fgets Functions 



The gets and fgets functions read strings from stream files, fgets reads a string including 
a newline (line-feed) character, gets deletes the newline, and reads only from the standard 
input. Both functions terminate the strings with a null character. 

You must specify a maximum count with fgets, but not with gets. This count includes 
the terminating null character. 



Calling Sequence: 



BYTE 


*addr; 


BYTE 


*s; 


BYTE 


*gets(),*fgets(); 


WORD 


n; 


FILE 


* stream; 


addr = 


gets(s); 


addr = 


fgets(s,n,stream); 


Arguments: 




s 


the string bi 


n 


the maximu 


stream 


the input str 


Returns: 





addr 



the string buffer address 
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The index, rindex Functions 



The index, rindex Functions 



The index and rindex functions locate a given character in a string, index returns a 
pointer to the first occurrence of the character, rindex returns a pointer to the last 
occurrence. 



Calling Sequence: 

BYTEc; 

BYTE *s; 

BYTE *ptr; 

BYTE *index(),*rindex(); 

ptr = index(s,c); 
ptr = rindex(s,c); 

Arguments: 



a null-terminated string pointer 
the character for which to look 



Returns: 



ptr 




the desired character address 
character not in the string 
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The isatty Function 



A CP/M-68K program can use the isatty function to determine whether a file 
descriptor is attached to the CP/M-68K console device (CON:). 



Calling Sequence: 




WORD 


fd; 




WORD 


ret; 




ret = isatty (fd); 


Arguments: 






fd 




an open file descriptor 


Returns: 






1 




fd attached to CON: 







fd not attached to CON: 
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The lseek, tell Functions 



The lseek, tell Functions 



The lseek function positions a file referenced by the file descriptor to an arbitrary 
offset. Do not use this function with stream files, because the data in the stream buffer 
might be invalid. Use the fseek function instead. 

The tell function determines the file offset of an open file descriptor. 

Calling Sequence: 

WORD fd; 

WORD ptrname; 

LONG offset,lseek(),tell(),ret; 

ret = lseek(fd, offset, ptrname); 
ret = tell (fd); 



Arguments: 

fd 

offset 

ptrname 



the open file descriptor 

a signed byte offset in the file 

the interpretation of offset: 

= > from the beginning of the file 

1 = > from the current file position 

2 = > from the end of the file 



Returns: 



ret 
-1 



resulting absolute file offset 
error 



Note: 



Incompatible with versions 1 through 6 of UNIX. 
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The mktemp function creates a temporary filename. The calling argument is a 
character string ending in 6 X characters. The temporary filename overwrites these 
characters. 

Calling Sequence: 

BYTE * string; 
BYTE *mktemp(); 

string = mktemp (string) 
Arguments: 

string the address of the template string 

Returns: 

string the original address argument 
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The open, opena, openb Functions 

The open and opena functions open an existing ASCII file by file descriptor. The 
openb function opens an existing binary file. The file can be opened for reading, writing, 
or updating. 

Calling Sequence: 

BYTE *name; 
WORD mode; 
WORD fd; 

fd = open(name,mode); 
fd = opena(name,mode); 
fd = openb (name,mode); 



Arguments: 

name 
mode 



the null-terminated filename string 
the access desired: 

= > Read-Only 

1 = > Write-Only 

2 = > Read- Write (update) 



Returns: 



fd 
-1 



the file descriptor for accessing the file 
open failure 



Note: 



UNIX programs that use binary files compile correctly, but execute improperly. 
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The perror Function 

The perror function writes a short message on the standard error file that describes 
the last system error encountered. First an argument string prints, then a colon, then the 
message. 

CP/M-68K C simulates the UNIX notion of an external variable, errno, that contains 
the last error returned from the operating system. Appendix A contains a list of the 
possible values of errno and of the messages that perror prints. 

Calling Sequence; 

BYTE *s; 
WORD err; 

err = perror(s); 

Arguments: 



the prefix string to be printed 



Returns: 



err value of "errno" before call 

Note: 

Many messages are undefined on CP/M-68K. 
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The printf, fprintf, sprintf Functions 

The printf functions format data for output. The printf function outputs to the 
standard output stream. The fprintf function outputs to an arbitrary stream file. The 
sprintf function outputs to a string (memory). 

Calling Sequence: 

WORD ret; 

BYTE *fmt; 

FILE * stream; 

BYTE * string; 

BYTE *sprintf(),rs; 

/* Args can be any type */ 

ret = printf (fmt,argl,arg2 ...); 

ret = fprintf (stream,fmt,argl,arg2 ...); 

rs = sprintf(string,fmt,argl,arg2 ...); 

Arguments: 

fmt format string with conversion specifiers 

argn data arguments to be converted 

stream output stream file 

string buffer address 

Returns: 



ret number of characters output 

-1 if error 
rs buffer string address 

null if error 

Conversion Operators 

A percent sign, %, in the format string indicates the start of a conversion operator. 
Values to be converted come in order from the argument list. Table 2-2 defines the valid 
conversion operators. 
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Table 2-2. Conversion Operators 


Operator 


Meaning 


d 


Converts a binary number to decimal ASCII and inserts in output 




stream. 


o 


Converts a binary number to octal ASCII and inserts in output stream. 


X 


Converts a binary number to hexadecimal ASCII and inserts in output 




stream. 


c 


Uses the argument as a single ASCII character. 


s 


Uses the argument as a pointer to a null-terminated ASCII string, and 




inserts the string into the output stream. 


u 


Converts an unsigned binary number to decimal ASCII and inserts in 




output stream. 


0/ 

/o 


Prints a % character. 



You can insert the following optional directions between the % character and the 
conversion operator: 

■ A minus sign justifies the converted output to the left, instead of the default right 
justification. 

■ A digit string specifies a field width. This value gives the minimum width of the 
field. If the digit string begins with a character, zero padding results instead of 
blank padding. An asterisk takes the value of the width field as the next argument 
in the argument list. 

■ A period separates the field width from the precision string. 

■ A digit string specifies the precision for floating-point conversion, which is the 
number of digits following the decimal point. An asterisk takes the value of the 
precision field from the next argument in the argument list. 

■ The character 1 or L specifies that a 32-bit long value be converted. A capitalized 
conversion code does the same thing. 
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The putc, putchar, fputc, putw, putl Functions 

The putc, putchar, fputc, putw, and putl functions output characters and words to 
stream files. 

The putc function outputs a single 8-bit character to a stream file. This function is 
implemented as a macro in <stdio.h>, so do not use arguments with side effects. The 
fputc function provides the equivalent function as a real function. 

The putchar function outputs a character to the standard output stream file. This 
function is also implemented as a macro in <stdio.h>. Avoid using side effects with 
putchar. 

The putw function outputs a 16-bit word to the specified stream file. The word is 
output high byte first, compatible with the write function call. 

The putl function outputs a 32-bit longword to the stream file. The bytes are output 
in 68000 order, as with the write function call. 

Calling Sequence: 

BYTE c; 
FILE * stream; 
WORD w,ret; 
LONG lret,putl(),l; 

ret = putc(c,stream); 
ret = fputc(c,stream); 
ret = putchar(c); 
ret = putw(w,stream); 
lret = putl(l,stream); 
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Arguments: 



c 

stream 
w 
1 



the character to be output 
the output stream address 
the word to be output 
the long to be output 



Returns: 



ret 

lret 

-1 



the word or character output 
the long output with putl 
an output error 



Note: 



A -1 return from putw or putl is a valid integer or long value. Use ferror to detect 
write errors. 
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The puts, fputs Functions 

The puts and fputs functions output a null-terminated string to an output stream. 

The puts function outputs the string to the standard output, and appends a newline 
character. 

The fputs function outputs the string to a named output stream. The fputs function 
does not append a newline character. 

Neither routine copies the trailing null to the output stream. 

Calling Sequence: 



WORD 


ret; 




BYTE 


*s; 




FILE 


* stream; 


ret = puts(s) 


> 


ret = fputs (s,stream); 


Arguments: 






s 




the string to be output 


stream 




the output stream 


Returns: 






ret 




the last character output 


-1 




error 


Note: 







The newline incompatibility is required for compatibility with UNIX. 
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The qsort Function 

The qsort function is a quick sort routine. You supply a vector of elements and a 
function to compare two elements, and the vector returns sorted. 

Calling Sequence: 

WORD ret; 
BYTE *base; 
WORD number; 
WORD size; 
WORD compare(); 

ret = qsort (base, number, size, compare); 

Arguments: 

base the base address of the element vector 

number the number of elements to sort 

size size of each element in bytes 

compare the address of the comparison function 

This function is called by the following: 

ret = compare(a,b); 

The return is: 

< if a < b 
= if a = b 
> if a > b 



Returns: 



always 
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The rand, srand Functions 

The rand and srand functions constitute the C language random number generator. 
Call srand with the seed to initialize the generator. Call rand to retrieve random numbers. 
The random numbers are C int quantities. 

Calling Sequence: 

WORD seed; 
WORD rnum; 

rnum = srand (seed); 
rnum = rand (); 

Arguments: 



seed an int random number seed 

Returns: 

rnum desired random number 
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The read Function 



The read function reads data from a file opened by the file descriptor using open or 
creat. You can read any number of bytes, starting at the current file pointer. 

Under CP/M-68K, the most efficient reads begin and end on 128-byte boundaries. 

Calling Sequence: 

WORD ret; 
WORD fd; 
BYTE *buffer; 
WORD bytes; 

ret = read (fd, buffer, bytes); 
Arguments: 



fd a file descriptor open for read 

buffer the buffer address 

bytes the number of bytes to be read 



Returns: 



ret 
-1 



number of bytes actually read 
error 
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The scanf, fscanf, sscanf Functions 

The scanf functions convert input format. The scanf function reads from the standard 
input, fscanf reads from an open stream file, and sscanf reads from a null-terminated 
string. 

Calling Sequence: 

BYTE * format,* string; 

WORD nitems; 

FILE * stream; 

/* Args can be any type */ 

nitems = scanf (format,argl,arg2 ...); 
nitems = fscanf (stream,format,argl,arg2 ...); 
nitems = sscanf (string,format,argl,arg2 ...); 



Arguments: 



format 


the control string 


argn 


pointers to converted data locations 


stream 


an open input stream file 


string 


null-terminated input string 


Returns: 




nitems 


the number of items converted 


-1 


I/O error 


Control String Format 



The control string consists of the following items: 

■ Blanks, tabs, or newlines (line-feeds) that match optional white space in the 
input. 

■ An ASCII character (not % ) that matches the next character of the input stream. 

■ Conversion specifications, consisting of a leading %, an optional * (which 
suppresses assignment), and a conversion character. The next input field is 
converted and assigned to the next argument, up to the next inappropriate 
character in the input or until the field width is exhausted. 
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Conversion characters indicate the interpretation of the next input field. The following 
table defines valid conversion characters. 



Table 2-3. Valid Conversion Characters 



Character 


Meaning 


% 


A single % matches in the input at this point; no conversion is 
performed. 


d 


Converts a decimal ASCII integer and stores it where the next argu- 




ment points. 





Converts an octal ASCII integer. 


X 


Converts a hexadecimal ASCII integer. 


s 


A character string, ending with a space, is input. The argument pointer 
is assumed to point to a character array big enough to contain the 
string and a trailing null character, which are added. 


c 


Stores a single ASCII character, including spaces. To find the next 
nonblank character, use %ls. 


[ 


Stores a string that does not end with spaces. The character string is 
enclosed in brackets. If the first character after the left bracket is not 
A , the input is read until the scan comes to the first character not within 
the brackets. If the first character after the left bracket is A , the input 
is read until the first character within the brackets. 



Note: 



You cannot determine the success of literal matches and suppressed assignments. 
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The setjmp, longjmp Functions 

The setjmp and longjmp functions execute a nonlocal GOTO. The setjmp function 
initially specifies a return location. You can then call longjmp from the procedure that 
invoked setjmp, or any subsequent procedure, longjmp simulates a return from setjmp 
in the procedure that originally invoked setjmp. A setjmp return value passes from the 
longjmp call. The procedure invoking setjmp must not return before longjmp is called. 

Calling Sequence: 

#include <setjmp.h> 
WORD xret,ret; 
jmp_buf env; 

xret = setjmp(env); 

longjmp (env,ret); 

Arguments: 

env contains the saved environment 

ret the desired return value from setjmp 



Returns: 



xret when setjmp invoked initially 

copied from ret when longjmp called 



Note: 



awkward 
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The signal Function 



The signal function connects a C function with a 68000 exception condition. Each 
possible exception condition is indicated by a number. The following table defines 
exception conditions. 



Table 2-4. 68000 Exception Conditions 



Number 



Condition 



5 

6 

8 

10 



Illegal instruction trap. Includes illegal instructions, privilege viola- 
tion, and line A and line F traps. 

Trace trap. 

Trap instruction other than 2 or 3; used by BDOS and BIOS. 

Arithmetic traps: zero divide, CHK instruction, and TRAPV instruction. 

BUSERR (nonexistent memory) or addressing (boundary) error trap. 



All other values are ignored for compatibility with UNIX. 

Returning from the procedure activated by the signal resumes normal processing. The 
library routines preserve registers and condition codes. 
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Calling Sequence: 

WORD ret,sig; 
WORD func (); 

ret = signal (sig, func); 

Arguments: 

sig the signal number given above 

func the address of a C function 

Returns: 



ret if no error, -1 if sig out of range 
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The strcat, strncat Functions 

The strcat and strncat functions concatenate strings. The strcat function concatenates 
two null-terminated strings. The strncat function copies a specified number of characters. 

Calling Sequence: 

BYTE *sl,*s2,*ret; 
BYTE *strcat(),*strncat(); 
WORD n; 

ret = strcat(sl,s2); 
ret = strncat(sl,s2,n); 

Arguments: 

si the first string 

s2 the second string, appended to si 

n the maximum number of characters in si 

Returns: 

ret a pointer to si 

Note: 

The strcat (sl,sl) function never terminates and usually destroys the operating 
system because the end-of-string marker is lost, so strcat continues until it runs out 
of memory, including the memory occupied by the operating system. 
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The strcmp, strncmp Functions 



The strcmp and strncmp functions compare strings. The strcmp function uses null 
termination, and strncmp limits the comparison to a specified number of characters. 

Calling Sequence: 

BYTE *sl,*s2; 
WORD val,n; 

val = strcmp(sl,s2); 
val = strncmp(sl,s2,n); 



Arguments: 

si 

s2 
n 

Returns: 

val 



a null-terminated string address 
a null-terminated string address 
the maximum number of characters to compare 



the comparison result: 

<0 =>sl <s2 
= = > si = s2 
>0 => si >s2 



Note: 



Different machines and compilers interpret the characters as signed or unsigned. 
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The strcpy, strncpy Functions 

The strcpy and strncpy functions copy one null-terminated string to another. The 
strcpy function uses null-termination, while strncpy imposes a maximum count on the 
copied string. 

Calling Sequence: 

BYTE *sl,*s2,*ret; 
BYTE *strcpy(),*strncpy(); 
WORD n; 



ret = 


strcpy (sl,s2); 


ret = 


strncpy (sl,s2,n); 


Arguments 


: 


si 


the destination sti 


s2 


the source string 


n 


the maximum ch£ 


Returns: 




ret 


the address of si 


Note: 





If the count is exceeded in strncpy, the destination string is not null-terminated. 
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The strlen Function 

The strlen function returns the length of a null-terminated string. 

Calling Sequence: 

BYTE *s; 
WORD len; 

len = strlen(s); 

Arguments: 

s the string address 



Returns: 



len the string length 
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The swab Function 



The swab function copies one area of memory to another. The high and low bytes in 
the destination copy are reversed. You can use this function to copy binary data from a 
PDP-11™ or VAX™ to the 68000. The number of bytes to swap must be even. 

Calling Sequence: 

WORD ret; 
BYTE * from,* to; 
WORD nbytes; 

ret = swab(from,to,nbytes); 

Arguments: 

from the address of the source buffer 

to the address of the destination 

nbytes the number of bytes to copy 



Returns: 



ret 



always 



2-50 



D DIGITAL RESEARCH 1 



C Language Programming Guide The ttyname Function 

The ttyname Function 

The ttyname function returns a pointer to the null-terminated filename of the terminal 
device associated with an open file descriptor. 

Calling Sequence: 



BYTE *name,*ttyname(); 
WORD fd; 


name = 


: ttyname (fd); 


Arguments: 




fd 


an open file descriptor 


Returns: 





A pointer to the null-terminated string CON: if the file descriptor is open and 
attached to the CP/M-68K console device. Otherwise, zero (NULL) returns. 
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The ungetc Function 

The ungetc function pushes a character back to an input stream. The next getc, getw, 
or getchar operation incorporates the character. One character of buffering is guaranteed 
if something has been read from the stream. The fseek function erases any pushed-back 
characters. You cannot ungetc EOF (-1). 

Calling Sequence: 

BYTE c; 
FILE * stream; 
WORD ret; 

ret = ungetc(c,stream); 

Arguments: 

c the character to push back 

stream the stream address 



Returns: 



ret c if the character is successfully pushed back 

-1 error 
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The unlink Function 



The unlink function deletes a named file from the file system. The removal operation 
fails if the file is open or nonexistent. 



Calling Sequence: 



WORD 


ret; 


BYTE 


*name; 


ret = unlink(name); 


Arguments: 




name 


the null-terminated filename 


Returns: 







success 


-1 


failure 
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The write Function 

The write function transfers data to a file opened by file descriptor. Transfer begins 
at the present file pointer, as set by previous transfers or by the lseek function. You can 
write any arbitrary number of bytes to the file. The number of bytes actually written 
returns. If the number of bytes written does not match the number requested, an error 
occurred. 

Under CP/M-68K, the most efficient writes begin and end on 128-byte boundaries. 

Calling Sequence: 

WORD fd; 

BYTE *buffer; 

WORD bytes; 

WORD ret; 

ret = write(fd,buffer,bytes); 

Arguments: 

fd the open file descriptor 

buffer buffer the starting buffer address 

bytes bytes the number of bytes to write 



Returns: 



ret the number of bytes actually written 

-1 errors 



Note: 



Due to the buffering scheme used, all data is not written to the file until the file is closed. 

End of Section 2 
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To make your C language programs portable, readable, and easy to maintain, follow 
the stylistic rules presented in this section. However, no rule can predict every situation; 
use your own judgment in applying these principles to unique cases. 



3.1 Modularity 

Modular programs reduce porting and maintenance costs. Modularize your pro- 
grams, so that all routines that perform a specified function are grouped in a single 
module. This practice has two benefits: first, the maintenance programmer can treat 
most modules as black boxes for modification purposes; and second, the nature of data 
structures is hidden from the rest of the program. In a modular program, you can change 
any major data structure by changing only one module. 

3.1.1 Module Size 

A good maximum size for modules is 500 lines. Do not make modules bigger than 
the size required for a given function. 

3.1.2 Intermodule Communication 

Whenever possible, modules should communicate through procedure calls. Avoid 
global data areas. Where one or more compilations require the same data structure, use 
a header file. 



«*> 
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3.1.3 Header Files 

In separately combined files, use header files to define types, symbolic constants, and 
data structures the same way for all modules. The following list gives rules for using 
header files. 

■ Use the '#include "file.h"' format for header files that are project-specific. Use 
'#include <file.h>' for system-wide files. Never use device or directory names 
in an include statement. 

■ Do not nest include files. 

■ Do not define variables other than global data references in a header file. Never 
initialize a global variable in a header file. 

■ When writing macro definitions, put parentheses around each use of the parame- 
ters to avoid precedence mix-ups. 



3.2 Mandatory Coding Conventions 

To make your programs portable, you must adhere strictly to the conventions 
presented in this section. Otherwise, the following problems can occur: 

■ The length of a C int variable varies from machine to machine. This can cause 
problems with representation and with binary I/O that involves int quantities. 

o The byte order of multibyte binary variables differs from machine to machine. 
This can cause problems if a piece of code views a binary variable as a byte stream. 

■ Naming conventions and the maximum length of identifiers differ from machine 
to machine. Some compilers do not distinguish between upper- and lower-case 
characters. 

■ Some compilers sign-extend character and short variables to int during arithmetic 
operations; some compilers do not. 

■ Some compilers view a hex or octal constant as an unsigned int; some do not. 
For example, the following sequence does not always work as expected: 

LONG data? 



printf ("XldXn" ><data & 0xffff)>5 
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The printf statement prints the lower 16 bits of the long data item data. However, 
some compilers sign-extend the hex constant Oxffff. 

■ You must be careful of evaluation-order dependencies, particularly in compound 
BOOLEAN conditions. Failure to parenthesize correctly can lead to incorrect 
operation. 

3.2.1 Variable and Constant Names 

Local variable names should be unique to eight characters. Global variable names 
and procedure names should be unique to six characters. All variable and procedure 
names should be completely lower-case. 

Usually, names defined with a #define statement should be entirely upper-case. The 
only exceptions are functions defined as macros, such as getc and isascii. These names 
should also be unique to eight characters. 

You should not redefine global names as local variables within a procedure. 

3.2.2 Variable Typing 

Using standard types is unsafe in programs designed to be portable due to the 
differences in C compiler standard type definitions. Instead, use a set of types and storage 
classes defined with typedef or #define. The following tables define C language types 
and storage classes. 
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Table 3-1. Type Definitions 



Type 


CBase 


Type 




LONG 


signed long 




(32 bits) 


WORD 


signed short 




(16 bits) 


UWORD 


unsigned short 




(16 bits) 


BOOLEAN 


short 




(16 bits) 


BYTE 


signed char 




(8 bits) 


UBYTE 


unsigned char 




(8 bits) 


VOID 


void (function return) 




DEFAULT 


int 




(16/32 bits) 



Table 3-2. Storage Class Definitions 



Class 


CBase Class 


REG 


register variable 


LOCAL 


auto variable 


MLOCAL 


module static variable 


GLOBAL 


global variable definition 


EXTERN 


global variable reference 



Additionally, you must declare global variables at the beginning of the module. Define 
local variables at the beginning of the function in which they are used. You must always 
specify the storage class and type, even though the C language does not require this. 

3.2.3 Expressions and Constants 

"Write all expressions and constants to be implementation-independent. Always use 
parentheses to avoid ambiguities. For example, the construct 

if(c = getchar() = = '\n') 

does not assign the value returned by getchar to c. Instead, the value returned by getchar 
is compared to '\n', and c receives the value or 1 (the true/false output of the 
comparison). The value that getchar returns is lost. Putting parentheses around the 
assignment solves the problem: 

if((c = getchar()) = = '\n') 
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Write constants for masking, so that the underlying int size is irrelevant. In the 
following example, 

LONG data! 



p r i n t f ( " "L 1 d /n " t ( d at a & Ox f f f f L) » 

the long masking constant solves the previous problem for all compilers. Specifying 
the one's complement often yields the desired effect, for example, "Oxff instead 
of OxffOO. 

For portability, character constants must consist of a single character. Place multi- 
character constants in string variables. 

Commas that separate arguments in functions are not operators. Evaluation order is 
not guaranteed. For example, the following function call 

printf("5f,d 7, d \ n " » i ++ t i ++ ) > 

can perform differently on different machines. 

3.2.4 Pointer Arithmetic 

Do not manipulate pointers as ints or other arithmetic variables. C allows the addition 
or subtraction of an integer to or from a pointer variable. Do not attempt logical 
operations, such as AND or OR, on pointers. A pointer to one type of object can convert 
to a pointer to a smaller data type with complete generality. Converting a pointer to a 
larger data type can yield alignment problems. 

You can test pointers for equality with other pointer variables and constants, notably 
NULL. Arithmetic comparisons, such as > = , do not work on all compilers and can 
generate machine-dependent code. 

When you evaluate the size of a data structure, remember that the compiler might 
leave holes in a data structure to allow for alignment. Always use the sizeof operator. 



] DIGITAL RESEARCH" 



3-5 



3.2 Mandatory Coding Conventions C Language Programming Guide 

3.2.5 String Constants 

Allocate strings so that you can easily convert programs to foreign languages. The 
preferred method is to use an array of pointers to constant strings, which is initialized 
in a separate file. This way, each string reference then references the proper element of 
the pointer array. 

Never modify a specific location in a constant string, as in the following example: 

6YTE strin*C3 ="6D0S Error On x : " i 



strina[143 = 'fl'i 

Foreign-language equivalents are not likely to be the same length as the English version 
of a message. 

Never use the high-order bit of an ASCII string for bit flags. Extended character sets 
make extensive use of the characters above 0x7F. 

3.2.6 Data and BSS Sections 

Usually, C programs have three sections: text (program instructions), data (initialized 
data), and BSS (uninitialized data). Avoid modifying initialized data if at all possible. 
Programs that do not modify the data segment can aid the swapping performance and 
disk utilization of a multiuser system. 

Also, if a program does not modify the data segment, you can place the program in 
ROM with no conversion. This means that the program does not modify initialized static 
variables. This restriction does not apply to the modification of initialized automatic 
variables. 



H DIGITAL RESEARCH" 

3-6 



C Language Programming Guide 3.2 Mandatory Coding Conventions 

3.2.7 Module Layout 

The following list tells you what to include in a module. 

■ At the beginning of the file, place a comment describing the following items: 

— the purpose of the module 

— the major outside entry points to the module 

— any global data areas that the module requires 

— any machine or compiler dependencies 

■ Include file statements. 

■ Module-specific #define statements. 

■ Global variable references and definitions. Every variable should include a 
comment describing its purpose. 

■ Procedure definitions. Each procedure definition should contain the following 
items: 

— A comment paragraph, describing the procedure's function, input parameters, 
and return parameters. Describe any unusual coding techniques here. 

— The procedure header. The procedure return type must be explicitly specified. 
Use VOID when a function returns no value. 

— Argument definitions. You must explicitly declare storage class and variable type. 

— Local variable definitions. Define all local variables before any executable 
code. You must explicitly declare storage class and variable type. 

— Procedure code. 

Refer to Appendix C for a sample program. 
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3.3 Suggested Coding Conventions 

The following suggestions increase program portability and make programs easier 
to maintain. 

■ Keep source code within an 80-character margin for easier screen editing. 

■ Use a standard indention technique, such as the following: 

— Begin statements in a procedure one tab stop (column eight) from the left 
margin. 

— Indent statements controlled by an if, else, while, do, or for, one tab stop. If 
you require multiple nested indentions, use two spaces for each nesting level. 
Avoid going more than five levels deep. 

— Place the brackets surrounding each compound statement on a separate line, 
aligned with the indention of the controlling statement. For example, 

fori i=0ii<MAXNUM5i++) 
•C 

J = compute(i) 5 

if (J > UPPER) 

J = UPPER," 

output! j) ; 



> 



- Place a null statement controlled by an if, else, while, for, or do, on a separate 
line, indented for readability. 

To document your code, insert plenty of comments. If your code is particularly 
abstruse, inserting comments helps clarify it. 

Put all maintenance documentation in the source code itself. If you do not, the 
documentation will not be updated when the code changes. 

Use blank lines, form-feeds, and white space to improve readability. 

End of Section 3 
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CP/M-68K Error Codes 



The perror function and the errno external variable determine the cause of an error 
during a CP/M-68K system call. The include file <errno.h> contains symbolic definitions 
for the errors that CP/M-68K returns. The following table lists error numbers, symbolic 
names, and messages available from perror. 



Table A-l. CP/M-68K Error Codes 



Number 


Name 


Error Message 





- 


Error Undefined on CP/M-68K 


1 


- 


Error Undefined on CP/M-68K 


2 


ENOENT 


No Such File 


3 


- 


Error Undefined on CP/M-68K 


4 


- 


Error Undefined on CP/M-68K 


5 


EIO 


I/O Error 


6 


- 


Error Undefined on CP/M-68K 


7 


E2BIG 


ftri List too L o n 3 


8 


- 


Error Undefined on CP/M-68K 


9 


EBADF 


Bad file Number 


10 


- 


Error Undefined on CP/M-68K 


11 


- 


Error Undefined on CP/M-68K 


12 


ENOMEM 


Not enough core 


13 


EACCES 


Permission denied 


14 


- 


Error Undefined on CP/M-68K 


15 


- 


Error Undefined on CP/M-68K 


16 


- 


Error Undefined on CP/M-68K 


17 


- 


Error Undefined on CP/M-68K 


18 


- 


Error Undefined on CP/M-68K 


19 


- 


Error Undefined on CP/M-68K 


20 


- 


Error Undefined on CP/M-68K 



8> 
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Table A-l. 


(continued) 


Number 


Name 


Error Message 


21 


- 


Error Undefined on CP/M-68K 


22 


EINUAL 


Invalid arS u m e n t 


23 


ENFILE 


File table overflow 


24 


EMFILE 


Too wanv open files 


25 


ENDTTY 


Not a typewriter 


26 


- 


Error Undefined on CP/M-68 K 


27 


EFBIG 


File too bis 


28 


ENDSPC 


No space left on device 


29 


- 


Error Undefined on CP/M-68 K 


30 


EROFS 


Read-Only file system 


31 


- 


Error Undefined on CP/M-68 K 


32 


- 


Error Undefined on CP/M-68K 


33 


- 


Error Undefined on CP/M-68K 


34 


- 


Error Undefined on CP/M-68K 


35 


ENODSPC 


No directory space 



The file <errno.h> also includes the names for all errors defined with UNIX V7. 
Therefore, programs that reference these definitions need not be changed. 



End of Appendix A 



m DIGITAL RESEARCH" 



A-2 



Appendix B 
Customizing the C Compiler 



Compiling a C program requires three compiler passes. The output of the compiler 
is assembly language, which must be assembled and linked to produce a program that 
runs. The compiler, assembler, linker load modules, C library, and the system include 
files need a substantial amount of disk storage space, minimizing storage space. This 
appendix discusses compiler operation and suggests ways to minimize the disk storage 
requirements for compiling. 



B.l Compiler Operation 

The C compiler has three components: the preprocessor (CP68), the parser (C068), 
and the code generator (C168). The assembler (AS68) and the linker (LO68) also help 
generate an executable program. The following list tells you how these components 
operate. 

1. The preprocessor, CP68, takes the original source file and produces a file with 
all #define and #include statements resolved. The preprocessor command line 
takes the form: |=s 

CP68 [-1 d:] file.C file.I W- 

The -I flag indicates that the next argument is a CP/M-68K drive specification. 
This drive is used for all library include statements of the form #include <file>. 
Drive specifications can also appear in the filename portion of an #include 
statement, but this procedure is not recommended. File.C is the source file, and 
file.I is the output file. 

2. The parser, C068, takes the file produced by the preprocessor and creates an 
intermediate code file. The command line takes the form: 

C068 file.I file.IC file.ST 

File.I is the output from the preprocessor. File.IC is the intermediate code file 
that CI 68 uses. File.ST is a temporary file that collects constant data for 
inclusion at the end of the intermediate code file. 
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3. The code generator, CI 68, takes the intermediate code file from C068 and 
produces an assembly-language source file. The command line takes the form: 

C168 file.IC file.S [-LD] 

File.IC is the intermediate code output from C068. File.S is the assembly- 
language output file. The -L flag indicates that the compilation assumes all 
address variables are 32 bits. The default is 16-bit addresses. The -D flag causes 
the compiler to include the line numbers from the source file (file.C) as com- 
ments in the generated assembly language. This is useful for debugging. 

4. The assembler, AS68, translates the compiler output to a form that the linkage 
editor can use. The command line takes the form: 

AS68 -L -U [-F d:] [-S d:] file.S 

The -L option indicates to the linkage editor that addresses are considered 32-bit 
quantities. The -U option means that undefined symbols are considered external 
references. The -F option specifies a drive that the assembler uses for temporary 
files. The -S option specifies a drive that the assembler uses for the initialization 
file (AS68SYMB.DAT). File.S is the output of C168, and file.O is produced by 
the assembler. 

5. The linker, LO68, produces an executable file from the output of one or more 
assembler runs. You must also include a start-up file and the C library when 
linking C programs. The linker command line takes the form: 

LO68 -R [-F d:] -O file.68K S.O file.O clib 

The -R option specifies that the file be relocatable. Relocatable files run on any 
CP/M-68K system. The -F option allows you to place linker temporary files on 
a disk drive other than the default. The -O file.68K construct makes the linker 
place the executable output in file.68K. S.O is the run-time start-up routine. 
You must include this file as the first file in every C program link. File.O is the 
output of the assembler. Specify multiple files between S.O and clib if you want 
separate compilation, clib is the C library file. 
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B.2 Supplied submit Files 

CP/M-68K includes two submit files, c.sub and clink.sub, that compile and link C 
programs (see Section 1.1). Usually, these files are located on the default drive. However, 
you can edit these files to specify different disk drives for any of the following drives: 

■ The disk drive on which the compiler passes, assembler, and linker reside. 

■ The disk drive that the #include <file> statements in the C preprocessor 
reference. 

■ The disk drive with the assembler initialization file. 

■ The disk drive on which the assembler and linker create temporary files. 
n The disk drive containing the C library file. 



B.3 Saving Disk Space 

You can do the following things to conserve disk space: 

n Use the reloc utility on all the load modules, the compiler, assembler, linker, and 
editor. This significantly reduces file size and load time. 

b Place all the load modules on one disk and use another disk for sources and 
temporary files. This requires two drives. 

b On single-density disk systems, you must place the C library file and linker on 
a separate disk and swap disks before linking. 
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B.4 Gaining Speed 

Along with the items in Section B.3, you can speed compilation by implementing the 
following: 

■ Put the assembler temp files on a different drive from the source and object files. 

■ Put the linker temp files on a different drive from the object input, C library, and 
load module output. 

■ Use the linker -S (suppress symbol table) and -T (absolute load module) switches 
in place of the -R flag. If you do this, the resulting program cannot run on an 
arbitrary CP/M-68K system. 

End of Appendix B 
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The modules in this appendix are written and documented in C code that follows the 
style conventions discussed in Section 3. 

/*#****##*****#*#********#****###*********#************##****#*********#***##/ 

/* */ 

/* -Printf Module */ 

/* */ 

/* */ 

/* This module is called through the single entry point "_printf" to */ 

/* perform the conversions and output for the library functions: */ 

/* */ 

/* printf - Formatted print to standard output */ 

/* fprintf - Formatted print to stream file */ 

/ * sprintf- Formatted print to string */ 

/* */ 

/* The calling routines are logically a part of this modulet but are */ 

/* compiled separately to save space in the user's program when only */ 

/* one of the library routines is used. */ 

/* */ 

/* The following routines are present: */ 

/* */ 

/* _printf Internal printf conversion / output */ 

/* _prnt8 Octal conversion routine */ 

/* _prntx Hex conversion routine */ 

/* conv Decimal ASCII to binary routine */ 

/* _putstr Output character to string routine */ 

/* _prntl Decimal conversion routine */ 

/* */ 

/* The following routines are called: */ 

/* */ 

/* strlen Compute length of a strins */ 

/* putc Stream output routine */ 

/* ftoa Floating point output conversion routine */ 

/* */ 

/* */ 

/* This routine depends on the fact that the argument list is always */ 

/* composed of LONG data items. */ 

/* */ 

/* Configured for Whitesmith's C on VAX. "putc" arguments are */ 

/* reversed from UNIX. */ 

/* */ 
/***********#******#*#**##******#*********#*###*******#***#**#*#*#***#***#***/ 

/* 

* Include files: 

*/ 

ftinclude <stdio.h> /* Just the standard stuff */ 



(^ 
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/* 



* 


Local DEFINES 




*/ 






ftdef ine 


HIBIT 31 




/* 






* 


Local static data: 




*/ 








MLOCAL BYTE *_ptrbf 


= o; 




MLOCAL BYTE *_ptrst 


= o; 




MLOCAL BYTE *__fmt 


= Oi 



/* Hish bit number of LONG */ 



/* Buffer .Pointer */ 

/* -> File/strinS (if any) */ 
/* Format Pointer */ 

/*****###*****#****###*####♦*/ 



C-2 
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/♦♦♦ft************************************************************************* 

* 

* PRINTF INTERNAL ROUTINE 



* Routine "_printf" is used to handle all "printf" functions* including 

* "sprintf " i and "f printf" . 
* 

* Calling Sequence: 
* 

* _printf (fd »func tfmt iar3l ) ! 
# 

* Where: 
* 

* fd Is the file or string pointer. 

* func Is the function to handle output. 

* frnt Is the address of the format string, 

* arSl Is the address of the first aM. 



Returns 



Buss: 



Number of characters output 



* It is assumed that arSs are contiguous starting at "arSl"i and that 

* all are the same size (LONG)i except for floating point. 
* 

* 

/♦■a******************************/ 

/* Not really » but ... */ 

/* Function pointer */ 

/* -> Format strinS */ 

/* -> Ara list */ 
/***************#*****#****####**/ 

/* Format character temp */ 

/* Output string pointer */ 

/* Ri tfht/lef t adjust flaS */ 

/* Temporary buffer */ 
/♦a******************************/ 

/* ArS Address temporary */ 

/* AM Value temporary */ 

/* String Length Temp */ 

/* Field Length Temporary */ 

/* Field width */ 

/* Precision for "%x.yf" */ 

/* '0' or ' ' (paddinS) */ 

/* Floating temporary */ 

/* Floating temp, address */ 

/* Character count */ 

/* Reference function */ 



printf(fd»fffiiit»al) 




LONG fd! 




LONG (*f)()5 


BYTE *fmt> 




LONG *al! 




LOCAL BYTE 


c 5 


LOCAL BYTE 


*s ; 


LOCAL BYTE 


ad J ! 


LOCAL BYTE 


buf [30] i 


LOCAL LONG 


* a d x 5 


LOCAL LONG 


x ! 


LOCAL LONG 


n 5 


LOCAL LONG 


m ; 


LOCAL LONG 


width 5 


LOCAL LONG 


prec 5 


LOCAL LONG 


padchar 5 


LOCAL DOUBLE 


zz ; 


LOCAL DOUBLE 


*dblptri 


LOCAL LONG 


ccount 5 


EXTERN 


_putst r( ) i 
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ccount = 05 /* Initially no characters */ 

_ptrbf = buf? /* Set buffer pointer */ 

adx = al ; /* Copy address variable */ 

_ptrst = fd5 /* Copy file descriptor */ 

fmt = fmt» /* Copy format address */ 

/***#####*****##**#**#***###/ 
if(*__fmt == 'L' i! * — fmt = = '1') /* Skip Ion* output */ 

fmt++i /* conversions */ 

/* */ 

/##*#*******###*****####***####*******#*#####****** #/ 

/* This is the main format conversion loop. Load a character from the */ 
/* format string. If the character is '%' » perform the appropriate */ 
/* conversion. Otherwise! just output the character. */ 

/*#####*******#*******#*###*******####*******###### #/ 

/* */ 

while( c = * fmt++ ) /* Pick up next format char*/ 

{ /* */ 

/**#***####****#***####*#**#/ 
/* */ 

/* If not 'I' > Just output */ 
/* Bump character count */ 
/###****#*****##*##********#/ 
/* It is a '2 ' » */ 

/* convert */ 

/# x = address of next arS */ 
/**#***#***#**##****##******/ 
'-' ) /* Check for left adjust */ 

/#******#*##*#*#**#****#*###/ 
/* Is leftf set flaS */ 
/* Bump format pointer * 
/* */ 

/* RiSht adjust */ 

/****#*###***###**#######*##/ 
/* */ 

padchar=(* fmt == '0') ? '0' : ' '! /* Select Pad character */ 

/**#***#*##*#*##**#*##*##*##/ 
width = oonv()i /* Convert width (if any) */ 

if( * fmt == '.') /* '.' means precision spec*/ 

{ /* */ 

++ fmt5 /* Bump past '.' */ 

prec - conv()i /* Convert precision spec */ 

} /* */ 

else /* None specified */ 

prec = 0! /**#***##*#*#***#**#*#*###**/ 

/* */ 

s = Oi /* Assume no output strinS */ 

switch ( c = * fmt++ ) /* Next char is conversion */ 

{ /* */ 

case 'D': /* Decimal */ 

case 'd': /* */ 

_prtl(x)> /* Call decimal print rtn */ 

break! /* Go do output */ 



r 


f(c ! = '1') 


{ 






(*f )(fd»c) ! 




ccount++ 5 


} 






else 


{ 






x = *adx++i 




if( *__fmt 




{ 




adJ = '1' 




fmt++5 




} 




else 




ad J = ' r ' 



11 DIGITAL RESEARCH 7 



C-4 



C Language Programming Guide 



C Sample C Module 



case 'o ' : 
case '0 ' : 

_prntB( x ) 5 

break! 

case 'x ' : 
case ' X ' : 

_prntx( x ) 5 

break! 

case 'S': 
case 's ' : 

s = x ; 

break! 

case 'C ' : 
case 'c ' : 

*_ptrbf++ = X&0377! 

break! 

case 'E ' 
case 'e ' 
case 'F' 
case 'f 

dblptr = adx-15 

zz = *dblptr5 

adx = + 1 5 

f toa (zz > buf i prec » c) 5 

prec = 5 

s = buf! 

b reak i 

default: 
(*f )(fd»c) ; 
ccount++ ! 
adx-- 5 



if (s == 0) 
{ 

*_ptrbf = '0'; 

s = bufi 
} 

n = strlen (s)5 

n = (prec<n &e& prec != 0) ? prec 

m = width-n? 

if (adJ == 'r') 
while (m-- > 0) 
{ 

(*f ) (fd »padchar> 5 
ccount++ 5 
> 



/* Octal 
/* 

/* Call oc 
/* Go do o 
/********* 
/* Hex 
/* Pr 
/* Call co 
/* Go do o 
/*******#* 
/* Strin3 
/* 

/* Yes, (e 
/* Go fini 
/****#**** 
/* Charact 
/* Du 
/* Just lo 
/* Go outp 
/******#** 
/* Floatin 
/* 
/* 
/* 

/* Assumes 
/* Load ua 
/* Bump pa 
/* Call fl 
/* Fake ou 
/* Just li 
/* Go Outp 
/*****##** 
/* None of 
/* Just Du 
/* Count i 
/* Fix ar3 
/* End swi 
/********* 
/* If s = 
/* "buf" t 
/ * I n s u r 
/* Load 
/********* 
/* 

/* Compute 
n!/* Take mi 
/* m is « 
/*******## 
/* For rid 
/* Pad in 
/* 

/* Thusly 
/* Count i 
/* 
/***#***** 



*/ 
Print */ 

tal printer */ 
utput */ 

♦a****************/ 

*/ 
int */ 

nversion routine */ 
utput */ 

a*****************/ 

*/ 
Output? */ 
asy) */ 

sh up */ 

#****#*#**#*******/ 
er */ 

tPUt? */ 

ad buffer */ 

ut */ 

**#**********#****/ 

3 point? */ 

*/ 

*/ 

*/ 

Gfl bit float! */ 

lue */ 

st second word */ 

oat in ^ conversion*/ 

t paddinS routine*/ 

ke st rin3 print */ 

ut */ 

*********#******#*/ 

the above? */ 

tPUt */ 

t . */ 

address */ 
tch */ 

**************#***/ 
Of st rind is in */ 

*/ 
e termination */ 
address */ 
#********#******#*/ 

*/ 
conue rted length*/ 
n ( prec »n ) */ 

of pad characters*/ 
************#*****/ 
ht adjust t */ 

front */ 

*/ 

*/ 
t */ 

*/ 
*********#********/ 
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while (n--) 
i 

(*f )(fd»*s++) ; 

ccount++ > 
> 

while (M-- > 0) 
{ 

(*f ) (f d »padchar) 5 

ccount++ 5 
} 
_ptrbf = buf 5 



if ( (*f ) == -putstr) 
(*f Hfd.'O') ; 



return( ccount ) 5 



/* Output Converted */ 
/* */ 

/* Data */ 

/* Count it */ 

/* */ 

/*##***##*##*#*#####*####*##/ 
/* If left adjust* */ 
/* */ 

/# Pad */ 

/* Count padded characters */ 
/**#*#**#*#*##*##*##***##*##/ 
/* Reset buffer pointer */ 
/* End else */ 

/* End while */ 

/* If string output > */ 
/* Drop in terminator char */ 
/**#**##**#*****##*#**#***#*/ 
/* Return appropriate value*/ 
/* End -printf */ 
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/ft**********************************************************************/ 
/* */ 

/* _PRNT8PRQCEDURE */ 

/* */ 

/* */ 

/* Routine "_prntB" converts a binary LONG value to octal ascii. */ 
/* The area at "_ptrbf" is used. */ 

/* */ 

/* CallinS Sequence: */ 

/* */ 

/* _prnt8(n) ! */ 

/* */ 

/* "n" is the nurnber to be converted. */ 

/* */ 

/* Returns: */ 

/* */ 

/* (none) */ 

/* */ 

/***#**##*#*********#*#*#*##*###*******#****#**#*#**##***#***#**********/ 
VOID _prnt8 (n) /* */ 

LONG ni /* Number to convert */ 

{ /* */ 

REG WORD pi /* Counts bits */ 

REG WORD K5 /* Temporary 3-bit value */ 

REG WORD swi /* Switch 1 = > output */ 

/#***#**********###*#*#*####/ 

if (n==0) /* Handle as special case*/ 

{ /* */ 

*_ptrbf++ = 'O'i /* Put in one zero */ 

return! /* And quit */ 

} /* */ 

/###****#*#**######****#****/ 
su = o; /* Indicate no output yet */ 

/* */ 

for (p=HIBIT; p >= 05 p = - 3) /* Use 3 bits at a time */ 

/* */ 

if ((k = (n>>p)&07) !! sw) /* Need to output yet? */ 

{ /* */ 

if (p- = HIBIT) /* 1st disit has only 2 bits*/ 

K = k 8c 025 /* Mask appropriately */ 

*_ptrbf++ = '0' + ki /* ASCIIfy disfit */ 

sw = li /* Set output flaS */ 

} /* End if */ 

} /* End _prnt8 */ 

/a**************************/ 
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/**#*#*********************#*#*****#*##**#*****♦♦♦*####**##****#***##*♦####♦*/ 

/* */ 

/* -Prntx Function */ 

/* */ 

/* */ 

/* The "_pmtx" function converts a binary LONG quantity to hex ASCII */ 

/* and stores the result in "*_ptrbf". Leading zeros are suppressed. */ 

/* */ 

/* Calling sequence: */ 

/* */ 

/* _p rntx (n ) 5 */ 

/* */ 

/* where" n" is the value to be converted. */ 

/* */ 

/* Returns: */ 

/* */ 

/* (none ) */ 

/* */ 
/#**#**#**#********#**##**##***##*****#***##****♦###**#•)(•*#####**♦#*###****#**/ 

VOID _prntx (n) /* */ 

LONG n! /* 32 bits */ 
{ /a-*****************************/ 

REG LONG di /* A disit */ 

REG LONG a5 /* Temporary value */ 

/*****#****#*#***#**###*#*****#/ 

if (a = n>>4) /* Peel off low 4 bits */ 

_prntx ( a & Oxfffffff)! /* If <> 0> print first */ 

d = n&:017i /* TaKe low four bits */ 

*_ptrbf++ = d > 9 ? 'A'+d-10 : '0' + di/* ASCIIfy into buffer */ 
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/*#**#*#**#**##*♦****####**#**#*#****##**#**#**********#***###***♦#****#**»*#/ 
/* */ 

/* ..Con v Function */ 

/* --- --- */ 

/* */ 

/* Function " cony" is used to convert a decimal ASCII strinS in */ 

I* the format to binary. */ 

/* */ 

/* Cal 1 in3 Sequence: */ 

/* */ 

/* val = conv( ) i */ 

/* */ 

/♦Returns: */ 

/* */ 

/ * "val" is the converted value * / 

/ * Zero is returned if no ualue * / 

/* */ 

/****#*****#************#*******#***#***********#****##♦**###**♦******##*****/ 

LONG conv( ) /* */ 

{ /a***************************/ 

REG BYTE ci /* Character temporary */ 

REG LONG ni /* Accumulator */ 

/*********##***♦*#**#***#*#**/ 
n = Oi /* Zero found so far */ 

while(((c= * fmt++) >= '0') /* While c is a disit */ 

&& (c <= '9') ) /* */ 

n = n*10+c-'0'i /* Add c to accumulator */ 

__fmt--i /* BacK up format pointer to*/ 

/* character skipped above */ 

return(n)5 /* See» wasn't that simple? */ 

} /*#************#♦****#**#****/ 
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/* #/ 

/* _Putstr Function */ 

/* -- - -- */ 

/* */ 

/* Function "_putstr" is used by "sprintf" as the output function */ 
/* arSutnent to "_printf". A single character is copied to the buffer */ 

/* at "_ptrst". */ 

/* */ 

/* Callins Sequence: */ 

/* */ 

/* _putstr(str >chr) 5 */ 

/* */ 

/* where "str" is a dumniy argument necessary because the other output */ 

/* functions have two arguments. #/ 

/* */ 

/* Returns: */ 

/* */ 

/* (none) */ 

/* */ 
/#*****#*#*******#**##*************#**#****#***##*#*****#****#****#**#*#****#/ 

VOID _putstr(str»chr) /* */ 

REG BYTE ch r 5 /* The output character .*/ 

BYTE *5tr! /* Duinmy argument */ 
{ /*****##*#***#***##*****#****/ 

*_ptrst++ = chri /* Output the character */ 

return(O) i /* Go back */ 
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/* */ 

/* _Prtl Function */ 

/* --- */ 

/* */ 

/* Function "_prtl" converts a LONG binary quantity to decimal ASCII */ 

/* at the buffer pointed to by "_Ptrbf". */ 

/* */ 

/* Calling Sequence: */ 

/* */ 

/* _prtl (n) i */ 

/* */ 

/* where "n"isthevaluetobeconvertedi */ 

/* */ 

/* Returns: */ 

/* */ 

/* (none) */ 

/* */ 
/***#****#***#**#*******###*##******##*#*#*##*#***#******#*************###*#*/ 

VOID _prtl(n) /* */ 

REG LONG n! /* Conversion input */ 

{ /*##****#*#***#******#****###/ 

REG LONG di3sC15]5 /* store diaits here */ 

REG LONG *dpt! /* Points to last disit */ 

/##****************##*****#*#/ 

dpt = diss! /* Initialize disit pointer */ 

if (n >= 0) /* Fix */ 

n = -n'» /* up */ 

else /* sisn */ 

*_ptrbf++ = '-'! /* stuff */ 

for (> n ! : Oi n ; n/10) /* Divide by 10 till zero */ 

*dpt++ = nXlOi /* Store disit (reverse ord)*/ 

/********##****#**********#**/ 

if (dpt == diss) /* Zero value? */ 

*dpt++ = 0; /* Yes* store 1 zero disit */ 

/♦♦a*************************/ 

while (dpt != diss) /* Now convert to ASCII */ 

{ /* */ 

--dpti /* Decrement pointer */ 

*_ptrbf++ = '0' - *dpt» /* Note dibits are negative!*/ 

> /* */ 



End of Appendix C 
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Appendix D 
Error Messages 



This appendix lists the error messages returned by the components of the CP/M-68K 
C compiler, the C Parser, C068, the C Co-generator, C168, the C Preprocessor, CP68, 
and by the CP/M-68K C Run-time Library. The sections are arranged alphabetically. 
Error messages are listed within each section in alphabetical order with explanations 
and suggested user responses. 



D.l C068 Error Messages 

The CP/M-68K C Parser, C068, returns two types of error messages: diagnostic error 
messages and messages indicating errors in the internal logic of C068. Both types of 
error messages take the general form: 

*line no. error message text 

The asterisk (*) indicates that the error message comes from C068. The "error message 
text" describes the error. You must correct any errors you receive from C068 before 
invoking C168. Uncorrected errors from C068 cause erroneous error messages to occur 
when you run CI 68. 

D.l.l Diagnostic Error Messages 

These error messages occur mostly in response to syntax errors in the source code. 
Refer to your C language manual for a complete discussion of the C language syntax. 

The error messages are listed in Table D-l in alphabetical order with short explana- 
tions and suggested user responses. 





^v*J 
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Table D-l. C068 Diagnostic Error Messages 



Message Meaning 



*line no. address of register 



You have attempted to take the address of a register. Correct the 
source code before you recompile it. 



* 1 i 11 e noi ■■assignable operand required 

On the line indicated, the operand to the left of the equals sign in the 
assignment statement is not a valid operand. Supply a valid operand. 
This error might occur because the operand is a constant instead of a 
variable. 



* 1 i n e ii o ♦ bad character constant 

A character constant on the line indicated is invalid. The character 
constant must be a single character between quotes. A control charac- 
ter, more than one character, or a symbol that is not a character will 
cause this error to occur. 



* 1 i n e no. bad indirection 



You attempted to reference by address instead of by value, but the 
expression you used is not an address. Supply a value or a valid address 
before you recompile the source code. 



♦line no. can't open filename 



Either the filename or the drive code is incorrect. Specify the correct 
drive code and filename before you recompile the source code. 



♦ line no. case not-inside a switch block 

The case on the line indicated is not inside a switch block. Correct the 
source code before you recompile it. 



♦ line no. character constant too Ion 2 

The character constant on the line indicated is too long. A character 
constant must be a single character between quotes. Correct the source 
code before you recompile it. 



♦line no. constant required 



The operation on- the line indicated requires a constant. Correct the 
error before you recompile the source code. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no. declaration syntax 



The syntax of the declaration on the line indicated is incorrect. Refer 
to your C language manual. Correct the syntax before you recompile 
the source code. 



# 1 i n e no. default not inside a switch block 

The default on the line indicated is not inside a switch block. Correct 
the source code before you recompile it. 



* 1 i n e no. dimension table overflow 

There are too many dimensions, at or prior to the line indicated, for 
the dimension table. The dimension table does not have space for more 
than 8 or 9 dimensions. Structures count as dimensions. Rewrite the 
source code to use fewer dimensions and structures before you recom- 
pile it. 



* 1 i n e no. duplicate case value 

Two cases for the same switch are identical. Eliminate one of the cases 
before you recompile the source code. 



*line no. expected label 



A go to statement on the line indicated does not have a label. Supply 
the missing label before you recompile the source code. 



* 1 i n e no. expression too complex 

Due to internal limitations in C068, the expression on the line indi- 
cated is too complex to be evaluated. Simplify the expression before 
recompiling the source code. 



* 1 i n e no. external definition syntax 

The syntax of the external definition on the line indicated is incorrect. 
Correct the syntax before you recompile the source code. Refer to 
your C language manual for the correct syntax. 



*line no. field overflows byte 



The bit field asks for more bits than fit in an 8-bit byte. Reduce the 
number of bits in the bit field before you recompile the source code. 
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Table D-l. (continued) 



Message Meaning 



*line no. field ouerf lows word 



The word field asks for more bytes than fit in a word. Reduce the 
number of bytes in the byte field before you recompile the source code. 



*line no. floating point not supported 

CP/M-68K does not support floating point. Rewrite the source code 
before you recompile it. 



* 1 i n e no. function body s v n t a x 



There is no bracket at the beginning of the function on the line 
indicated. Supply the missing bracket before you recompile the source 
code. 



* 1 i n e no. illegal call 



You attempted to call something that is not a function. Correct the 
source code before you recompile it. 



* 1 i n e no. illegal function declaration 

The storage class of the function declared in the line indicated is illegal. 
The only two storage classes allowed for functions are static and 
external. Correct the declaration before you recompile the source 
code. 



♦ line no. illegal register specification 

The register specification in the line indicated is illegal. Structures and 
arrays cannot be put into a register. Correct the source code before 
you recompile it. 



♦ line no. illegal type conversion 

You made an incompatible assignment. This error commonly occurs 
when attempting to convert a pointer, 32 bits, to an int, 16 bits. 
Correct the source code before you recompile it. 



♦line no. indirection on function invalid 

You attempted to use the indirection operator (*) on a function. 
Correct the source code before you recompile it. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no. initializer alignment 

This message usually indicates a missing initializer value, or values 
out of order. Check the initializer list and correct it before you 
recompile the source code. 



# 1 i n e no. initializer list too Ion 3 

The initializer list is too long for C068. Shorten the list before you 
recompile the source code. 



* 1 i n e no. invalid break statement 

The break statement on the line indicated is not inside a loop or a 
switch. Correct the source code before you recompile it. 



# 1 i n e no. invalid character 



There is an invalid character in the collating sequence in the line 
indicated. Control characters or members of the extended character 
set are not valid characters. Correct the source code before you 
recompile it. 



* 1 i n e no. invalid continue s t a t e in e n t 

The continue statement on the line indicated is not inside a loop. This 
error might occur when you have used a continue statement in a 
switch. A continue statement is only valid in a loop. Correct the source 
code before reinvoking C068. 



* 1 i n e no. invalid conversion 



You attempted an incompatible assignment, for example, a pointer, 
32 bits, and an int, 16 bits. Correct the source code before you 
recompile it. 



* 1 i n e no. invalid data type 



The line indicated contains an expression that attempts to equate two 
incompatible quantities, for example, an int, 16 bits, and a pointer, 
32 bits. Correct the source code before you recompile it. 
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Table D-l. (continued) 



Message Meaning 



*line no. invalid declarator 



The declarator in the line indicated is not a recognizable language 
element. Supply a valid declarator before you recompile the source 
code. 



* 1 i n e no* invalid expression 



The expression in the line indicated contains a syntax error. Correct 
the syntax of the expression before you recompile the source code. 



*line no* invalid field size 



The field in the line indicated is less than or equal to zero. Correct the 
field size before you recompile the source code. 



* 1 i n e no* invalid field type description 

You attempted to put a pointer or a long into a bit field. Correct the 
source code before you recompile it. 



* 1 i n e no* invalid for statement 

The for statement in the line indicated contains a syntax error. Refer 
to your C language manual for the correct syntax of a for statement. 
Correct the statement before you recompile the source code. 



* 1 i n e no. invalid initializer 



The initializer you specified in the line indicated is not a constant. You 
can only initialize to a constant. Correct the source code before you 
recompile it. 



* 1 i n e no* invalid label 



You used a variable name as a label in the line indicated. Correct the 
source code before you recompile it. 



# 1 i n e no* invalid Ions declaration 

You attempted to declare something long that cannot be long, for 
example, a character. Correct the source code before you recompile it. 
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Table D-l. (continued) 



Message Meaning 



♦ line no* invalid operand type 



The expression in the line indicated contains an invalid operand. 
Correct the source code before you recompile it. 



♦ line no* invalid register specification 

You attempted to put something larger than allowed into a register, 
for example, a structure or a function. Correct the source code before 
you recompile it. 



♦ line no. invalid short declaration 

You attempted to declare something short that cannot be short. 
Correct the source code before you recompile it. 



♦ line no* invalid storage class 

You specified an invalid storage class in a declaration. Refer to your 
C language manual for the allowed storage classes. Correct the source 
code before you recompile it. 



* 1 i n e no. invalid structure declaration: name 

The size of the structure indicated by the variable name has a size 
less than or equal to zero. Correct the source code before you recom- 
pile it. 



♦ line no* invalid structure member name 

The structure reference in the line indicated is not a member of any 
structure. Correct the source code before you recompile it. 



♦line no. invalid structure prototype: name 

In the line indicated you reference a structure name that is not a 
prototype. Correct the source code before you recompile it. 



♦line no* invalid type declaration 

The type declared in the line indicated is invalid. Refer to your C 
language manual for a discussion of valid types. Correct the source 
code before you recompile it. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no. invalid typedef statement 

The line indicated contains a statement with more than one typedef 
keyword. Only one typedef is allowed per statement. Correct the 
source code before you recompile it. 



* 1 i n e no. invalid unsigned d e c 1 a r a t i o n 

The quantity you declared unsigned in the line indicated might not be 
unsigned. Only an int can be unsigned. Correct the declaration before 
you recompile the source code. 



* 1 i n e n o . invalid?: operator syntax 

This message indicates an error in the use of the ? : conditional operator 
in the line indicated. Refer to your C language manual for the correct 
syntax. Correct the source code before you recompile it. 



# 1 i n e no. label redeclaration: label 

You used the same label for two separate items. Correct the source 
code before you recompile it. 



* 1 i n e no. missind colon 



You left out a colon. Supply a colon in the correct location before you 
recompile the source code. 



* 1 i n e no. m i s s i n 5 -C in initialisation 

You neglected to put in the left curly brace in the initialization of an 
array or structure. Supply the missing brace before you recompile the 
source code. 



# 1 i n e no. missins } 



You left the right curly brace out of the initialization of an array or 
structure. Supply the missing brace before you recompile the source 
code. 



* 1 i n e no. wissins while 



The do statement at the line indicated is missing a while at the end. 
Supply the missing while before you recompile the source code. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no. missin 3 semicolon 



A semicolon is missing from the line indicated. Supply the missing 
semicolon before you recompile the source code. 



* 1 i n e n o . no structure n a m e 



You referred to a structure in the line indicated without giving the 
structure name. Correct the source code before you recompile it. 



* 1 i n e no. no*/ before EOF 



The last comment in the source code is missing its final delimiter. 
Supply the missing delimiter before you recompile the source code. 



* 1 i n e n o » not a structure: name 

The structure referenced in the line indicated is not a structure. Correct 
the source code before you recompile it. 



* 1 i n e no. not in parameter list 



In the line indicated, you declared the something indicated by the 
variable x to be an argument to a function, but x is not in the function 
parameter list. Correct the source code before you recompile it. 



*line no. parenthesized expression syntax 

The line indicated contains a syntax error in the parenthesized expres- 
sion. Correct the source code before you recompile it. 



* 1 i n e no. redeclaration: symbol 



A symbol has been declared twice. Remove one of the declarations 
before recompiling the source code. 



* 1 i n e no. strind cannot cross line 

The character string at the line indicated continues beyond one line. 
The closing quote to a character string must be on the same line as 
the opening quote, unless you use a backslash (\) at the end of the 
first line to indicate that the line continues. Correct the source code 
before you recompile it. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no. strin? too Ions 



The string at the line indicated is longer than 255 characters. A string 
cannot be longer than 255 characters on a single line. Break the string 
and use a continuation, indicated by a backslash ( \ ) at the end of the 
line to be continued. 



# 1 i n e no. structure declaration syntax 

The syntax of the structure declaration on the line indicated is incor- 
rect. Correct the syntax before reinvoking C068. 



*line no. structure operation not vet implemented 

On the line indicated, you assigned a structure to another structure. 
Assigning a structure to another structure is not yet supported by the 
CP/M-68K C compiler. Correct the source code before reinvoking 
C068. 



* 1 i n e no. structure table overflow 

There are too many structures in your program for the structure 
tables. Eliminate some structures before reinvoking the C compiler. 



#line no. symbol table overflow 

Your program uses too many symbols for the space available on the 
symbol table. Eliminate some symbols before reinvoking the C 
compiler. 



*line no. temp creation error 



The drive code or filename of the temporary file referenced in the line 
indicated is incorrect. Specify the correct drive code and filename 
before you recompile the source code. 



* 1 i n e no. too many cases in switch 

The switch at the line indicated has too many cases. Eliminate some 
cases before you recompile the source code. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no* too many initializers 

The initializer list in the line indicated contains more initializers than 
there are members of the array being initialized. Correct the list before 
you recompile the source code. 



* 1 i n e no* too Many params 



The function declaration at the line indicated contains too many 
parameters. Rewrite the source code before you recompile the source 
code. 



* 1 i n e no* undefined label: label 

The label indicated by the variable label has not been defined. 
Correct the source code before you recompile it. 



* 1 i n e no* undefined s v m b o 1 : symbol 

The symbol indicated by the variable s y m b o 1 is undefined. Correct 
the source code before you recompile it. 



*line no. unexpected EOF 



This error usually occurs when there is no right curly brace (}) after 
a function, or when there are mismatched comment delimiters. Locate 
and correct the error before you recompile the source code. 



*line no* u s a 3 e : c G8 source asm str 

The syntax of the C compiler command line is incorrect. The correct 
syntax is given in the error message. Reenter the command line using 
a valid syntax. 



* 1 i n e no. -C not matched by > 



A left curly brace ({) is not matched by a right curly brace. This error 
frequently occurs in an initialization sequence. Supply the missing 
brace before you recompile the source code. 
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Table D-l. (continued) 



Message Meaning 



* 1 i n e no* ="char" assume 



You have user a = + type operation with an invalid character. When 
an invalid character occurs after the = sign, C068 puts in = = instead 
of = . Correct the source code before you recompile the source code. 



•x-line no* & operand illegal 



You attempted to take the address of something that is not a variable, 
for example, a register. Correct the source code and recompile it. 



D.1.2 Internal Logic Errors 

These messages indicate fatal errors in the internal logic of C068 : 

# 1 i n e n o ♦ can't copy filename 

* 1 i n e no* i n v a 1 i d K e y word 

* 1 i n e no. too many chars pushed back 

* 1 i n e no* too litany tokens pushed back 

Contact the place you purchased your system for assistance. Provide the following 
information: 

■ Indicate the version of the operating system you are using. 

■ Describe your system's hardware configuration. 

■ Provide sufficient information to reproduce the error. Indicate which program 
was running at the time the error occurred. If possible, also provide a disk with 
a copy of the program. 
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D.2 CI 68 Error Messages 

The CP/M-68K C Co-generator, C168, returns two types of fatal error messages: 
diagnostic error messages and messages indicating errors in the internal logic of CI 68. 
Both types of error messages take the general form: 

**line no. error message text 

The asterisks (**) indicate that the error message comes from C168. The error message 
text describes the error. If you run C168 before correcting any errors you received from 
C068, you receive erroneous errors from C168. 

D.2.1 Fatal Diagnostic Errors 

The CI 68 fatal, diagnostic error messages are listed in Table D-2 in alphabetical 
order, with explanations and suggested user responses. 

Table D-2. C168 Fatal Diagnostic Errors 



Message Meaning 



**line no* can't create filename 

Either the drive code or the filename for the file indicated by the 
variable filename is incorrect. Ensure that you are requesting the 
correct drive code and filename before you recompile the source code. 



*#line no. can't open filename 



Either the drive code or the filename for the file indicated by the 
variable filename is incorrect. Ensure that you are requesting the 
correct drive code and filename before you recompile the source code.' 



**line no. divide by zero 



You attempted to divide by zero in the line indicated. Correct the 
source code before you recompile it. 



** 1 i n e no. expression too complex 

An expression on the line indicated is too complex for CI 68. Simplify 
the expression before you recompile the source code. 
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Table D-2. (continued) 



Message 


Meaning 


* * 1 i n e 


n o ♦ mo d u 1 u s b v zero 




The second operand of the percent operator in the line indicated is 




zero. Correct the source code before you recompile it. 


**1 ine 


no* structure operation not implemented 




The operation you attempted with a structure in the line indicated is 




illegal. Correct the source code before you recompile it. 


* * 1 i n e 


no* usase: clBB icode asm C-DLmec] 




The command line syntax is incorrect. The correct command line 




syntax is given in the error message. Correct the syntax before you 




reenter the command line. 



D.2.2 Internal Logic Errors 

The following messages indicate fatal errors in the internal logic of CI 68: 



* * 1 i n e no 

* * 1 i n e no 

* * 1 i n e no 

* * 1 i n e no 

* * 1 i n e no 

* * 1 i n e no 
# * 1 i n e no 
**line no 
# * 1 i n e no 
##1 ine no 



c d s i z e : i n v a 1 i d type 
code skeleton error: op 
hard lontf to register 
intermediate code error 
invalid initialization 
invalid operator op 
invalid register expression 
invalid storage class sc 
no code table for op 
s K e 1 m a t c h type: s t y p e 



If you receive one of these messages, contact the place where you purchased your system 
for assistance. Provide the following information: 

■ Indicate the version of the operating system you are using. 

■ Describe your system's hardware configuration. 

■ Provide sufficient information to reproduce the error. Indicate which program 
was running at the time the error occurred. If possible, also provide a disk with 
a copy of the program. 
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D.3 CP68 Error Messages 

The CP/M-68K C Preprocessor, CP68, returns two types of fatal error messages: 
diagnostic error messages and messages indicating errors in the internal logic of CP68. 
Both types of error messages take the general form: 

# line no. error message text 

The pound sign (#) indicates that the error message comes from CP68. The "error 
message text" describes the error. 

D.3.1 Diagnostic Error Messages 

A fatal diagnostic error message prevents CP68 from processing your file. The CP68 
diagnostic error messages are listed in Table D-3 with explanations and suggested user 
responses. 



Table D-3. CP68 Diagnostic Error Messages 



Message 



Meaning 



# 1 i n e n o ♦ arSument buffer overt lo w 

An argument list in the line indicated contains too many characters 
for the space allocated to the argument buffer. Reduce the number of 
characters in the argument list before rerunning CP68. 



# 1 i n e n o ♦ bad argument: arS 



In the line indicated, the argument represented by the variable a r g 
contains an invalid character. Replace or eliminate the invalid charac- 
ter before rerunning CP68. 
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Table D-3. (continued) 



Message Meaning 



# 1 i n e no» bad character octal n o ♦ 

The line indicated contains an illegal character. The ASCII code of the 
invalid character is represented by the variable octal no* Examine 
the line indicated to locate the error. Replace the character before 
rerunning CP68. 



# 1 i n e n o ♦ bad define name: name 

The name indicated by the variable name contains one or more 
invalid characters. Examine the name to locate the error. Replace the 
invalid characters before rerunning CP68. 



# 1 i n e no* bad include file 

The syntax of the ^include statement is incorrect. The ^include 
statement must follow one of the following two formats: 

#include <filename> 
#include "filename" 

Rewrite the statement before rerunning CP68. 



#line no. bad include file name 



In the line indicated, the filename in the # i n c 1 u d e statement con- 
tains either an invalid character or more than 8 characters, the 
maximum allowed. Supply a valid filename before rerunning CP68. 



# 1 i n e no* can't open f n a m e 



The ^include statement in the line indicated contains an invalid 
or nonexistent filename. Check the filename before rerunning CP68. 



# 1 i n e n o ♦ can't open in file 



CP68 cannot open the input file indicated by the variable i n f i 1 e . 
Either the drive code or the filename is incorrect. Check the drive code 
and the filename before rerunning CP68. 



#line no« can't open outfile 



CP68 cannot open the output file indicated by the variable outfile* 
Either the drive code is incorrect, or the disk to which CP68 is writing 
is full. Check the drive code. If it is correct, the file is full. Erase 
unnecessary files, if any, or insert a new disk before rerunning CP68 . 



D-16 



SB DIGITAL RESEARCH* 



C Language Programming Guide D.3 CP68 Error Messages 

Table D-3. (continued) 



Message Meaning 



« 1 i n e no. condition stack overflow 

The source code contains too many nested #if 's for the space allocated 
to the condition stack. The stack overflowed before the line indicated. 
Rewrite the source code before rerunning CP68. 



# 1 i n e no* define recursion 



A name or variable on the line indicated has been defined in terms of 
itself. Redefine the name before rerunning CP68. 



« 1 i n e no. define table overflow 

The source code contains one or a combination of the following: too 
many names, too many long names, too many expressions, or too 
many large expressions. The space allocated to the define table was 
filled before the line indicated. Simplify and rewrite the source code 
before rerunning CP68. 



# 1 i n e no. expression operator stack overflow 

An expression in the line indicated contains too many operations for 
the space allocated to the expression operator stack. Eliminate or 
consolidate some operations before rerunning CP68. 



ttline no. expression stack overflow 

An expression in the line indicated contains too many terms for the 
space allocated to the expression stack. Eliminate or consolidate some 
terms before rerunning CP68. 



* 1 i n e no. expression syntax 



The syntax of an expression in the line indicated is incorrect. Examine 
the line to locate the error. Correct the syntax before rerunning CP68. 



#line no. includes nested too deeply 

The ^include statement in the line indicated contains more than 
7 nested include files, the maximum allowed. Rewrite the source code 
so that no one ^include statement contains more than 7 nested 
include files. 



I DIGITAL RESEARCH" 



D-17 



D.3 CP68 Error Messages C Language Programming Guide 

Table D-3. (continued) 



Message Meaning 



« 1 i n e no. invalid ftelse 



A #else statement occurs in the source code without a preceding 
# i f statement. Supply the missing # i f statement or eliminate the 
ftelse statement before rerunning CP68. 



« 1 i n e no. invalid ftendif 



A # e n d i f statement occurs in the source code without a preceding 
»i f statement. Supply the missing 8i f statement or eliminate the 
8 e n d i f statement before rerunning CP68. 



8 1 i n e no. invalid, preprocessor command 

The command in the line indicated is either not valid for CP68 or is 
incorrectly formatted. Correct the command before rerunning CP68. 



8 1 i n e no. line overflow 



The line indicated contains more than 255 characters, the maximum 
allowed. Reduce the line to no more than 255 characters before 
rerunning CP68. 



8 1 i n e no. macro argument too lonsf 

An argument name in the line indicated contains more than 8 charac- 
ters, the maximum allowed. Use no more than 8 characters for the 
argument name, and rerun CP68. 



8 1 i n e no. no*/ before EQF 



A comment in the source code is missing the closing */. Supply the 
missing */ before rerunning CP68. 



8 1 i n e no. string cannot cross line 

A string in the line indicated is missing a closing quotation mark. 
Supply the missing quotation mark before rerunning CP68. 



8 1 i n e no. strins too Ions 



The line indicated contains a string greater than 255 characters, the 
maximum allowed. Shorten the string to no more than 255 characters 
before rerunning CP68. 
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Table D-3. (continued) 



Message Meaning 



» 1 i n e no* symbol table overflow 

The source code uses too many symbols for the space allocated to the 
symbol table. The symbol table was filled prior to the line indicated. 
Eliminate some symbols before rerunning CP68. 



* 1 i n e n o » too Manx ard u m ents 



One of the names in the line indicated contains more than 9 arguments, 
the maximum allowed. Reduce the number of arguments to no more 
than 9 per name before rerunning CP68. 



# 1 i n e no. unexpected EOF 



This message indicates an incomplete program. Examine the source 
code to locate the error. Correct before rerunning CP68. 



ttline no. unmatched conditional 

A * i f statement occurs in the source code without a matching 
« e n d i f statement. Supply the missing # e n d i f statement before 
rerunning CP68. 



ttline no* usaSe: cBS C-i x : ] inputfile outputfile 

This message indicates incorrect syntax in the command line. The 
correct syntax is given. Correct the command line before rerunning 
CP68. Refer to your C manual for an explanation of the command 
line syntax. 
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D . 3 .2 Internal Logic Errors 

CP68 returns only one message indicating an error in the internal logic of CP68: 

# 1 i n e no* too many characters pushed back 

If you receive this message, contact the place where you purchased your system for 
assistance. Provide the following information: 

■ Indicate the version of the operating system you are using. 

■ Describe your system's hardware configuration. 

■ Provide sufficient information to reproduce the error. Indicate which program 
was running at the time the error occurred. If possible, also provide a disk with 
a copy of the program. 

D.4 C-Run-time Library Error Messages 

The C-Run-time Library returns only one fatal error message, stack overflow. The 
stack overflow message means the program you are trying to include in the C-Run-time 
Library is too big. Reduce the size of the program. 

End of Appendix D 
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[, 2-42 
% 2-42 

%, 2-34, 2-42 
*, 2-34, 2-41 
-, 2-34 



assembler, 

initialization file, B-3 

temp files, B-3 
assembly-language source file, B-2 
atoi function, 2-6 
atol function, 2-6 
automatic variables, 1-1 



A.68K, 1-1 

abort function, 2-3 

abs function, 2-4 

absolute load module, B-4 

access function, 2-5 

addition, 3-5 

address variables, B-2 

addressing error trap, 2-44 

alignment, 2-22 

AND, 3-5 

alphanumeric characters, 2-22 

argc /argv interface, 1-5 

argument, 

absolute value of, 2-4 

pointer, 2-42 

same length, 1-4 

with side effects, 2-4, 2-13, 2-22, 5-35 
arithmetic comparison, 3-5 
arithmetic trap, 2-44 
AS68, B-l, B-2 
ASCII character, 2-34, 2-41 
ASCII files, 1-6, 2-18 

in CP/M-68K, 1-6 
ASCII string, 

converting to integer or binary, 2-6 

null-terminated, 2-34 



B 



binary and ASCII files, 

distinguishing, 1-6 
binary, 

files, 1-6, 2-18 

I/O, 3-2 
binary numbers, converting to decimal 

ASCII, 2-34 
bit flags, 3-6 
black boxes, 3-1 
blank padding, 2-34, 2-41 
block size, changing, 2-8 
blocks, releasing, 2-8 
bogus address, freeing, 2-8 
BOOLEAN condition, 3-3 
boundaries, 128 -byte, 2-40, 2-54 
brackets, 2-42, 3-8 
break location, 2-14 
brk function, 1-2, 2-7 
BSS, 1-1, 2-14, 3-6 
buffer flushing, 2-15 
BUSERR, 2-44 
BYTE, 3-4 

byte order, 2-22, 2-35 
byte stream, transferring, 2-20 
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-»r 



c 



c character, 2-42 
C Co-generator, D-l 
C language, 

functions implemented in, 2-2 

portability, 3-1 

program memory layout, 1-1 

program compiling, 1-1 
c operator, 2-34, 2-42 
C Parser, D-l 
C Preprocessor, D-l 
c.sub, 1-1, B-3 
C168, B-l, D-l 
calling conventions, 1-2 
calloc function, 2-8 
carriage return, 2-12 
carriage return line-feed, 1-6 
character, 8-bit, 2-35 
character class, 2-12 
character string, 2-42 
characters, locating in strings, 2-27 
CHK instruction, 2-44 
chmod function, 2-9 
chown function, 2-9 
clib, B-2 

clink.sub, 1-1, B-3 
close function, 2-10 
closing streamfiles, 2-16 
C068,B-1,D-1 
coding conventions, 

mandatory, 3-2 

suggested, 3-8 



code generator, B-l, B-2 
command line interface, 1-5 
commas, 3-5 

comments in a module, 3-7 
comparing two elements, 2-38 
compilation, speeding, B-4 
compiler, B-l, B-2, B-3, B-4 
compiler-generated code, 1-5 
compiling a C program, 1-1 
completion code, 2-15 
compound statement, 3-8 
CON:, 1-5, 2-28, 2-51 
concatenating strings, 2-46 
console device, 2-21, 2-28 
contiguous digits, 2-6 
control characters, 2-12 
control string format, 2-41 
controlling statement, 3-8 
conversion character, 2-41 
conversion code, capitalized, 2-34 
conversion operators, 2-33 

optional instructions in, 2-34 
conversion specifications, 2-41 
copying strings, 2-48 
CP68, B-l 

CP/M-68K C compiler, D-l 
CP/M-68K C Run-time Library, D-l 
creat function, 2-10, 2-11, 2-18, 2-40 
creata function, 2-11 
creatb function, 2-11 
CTRL-Z, 1-6 
ctype function, 2-12 
<ctype.h> file, 2-12 
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-D flag, B-2 
d character, 2-42 
d operator, 2-34 
data, 

conversion, 2-2 

region, 2-14 

structures, 3-1 
DDT-68K, 2-3 
decimal ASCII, 2-34 

integer conversion, 2-42 
DEFAULT, 3-4 
default drive, B-3 
# define statement, 3-3, B-l 

module-specific, 3-7 
deleting a file, 2-53 
destination string, 2-48 
/dev/lp, 1-5 
/dev/tty, 1-5 

device access, terminating, 2-10 
device I/O, 1-5 
digit string, 2-34 
disk space, conserving, B-l, B-3 
disks, swapping, B-3 
do, 3-8 

documenting code, 3-8 
drive changing, B-3 
dynamic memory allocation, 2-1 
dynamic memory areas, 

heap, 1-2 

stack, 1-2 



edata location, 1-2, 2-14 

editor, B-3 

EFBIG, A-2 

EINVAL, A-2 

EIO, A-l 

else, 3-8 

end, 1-2 

end location, 2-14 

end-of-file, 2-17 

errors, 2-23 
ENFILE, A-2 
ENODSPC, A-2 
ENOENT, A-l 
ENOMEN, A-l 
ENOSPC, A-2 
ENOTTY, A-2 
entry points, 2-2 
EROFS, A-2 

errno external variable, 2-32, A-l 
<errno.h>include file, A-l 
error, 

in specified stream, 2-17 

system-dependent, 2-3 
error file, 2-32 

error messages, numbers, 2-32, A-l 
error return, from getchar, 2-22 
etext location, 1-2, 2-14 
exception condition, 68000, 2-44 
executable file, B-2 
exit function, 2-15 
extended character sets, 3-6 
EXTERN, 3-4 
external, 

names, 1-4 

reference, B-2 

variable, 2-32 



E2BIG, A-l 
EACCES, A-l 
EBADF, A-l 
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-F option, B-2 

fcetc function, 2-22 

f close function, 2-10, 2-16 

feof function, 2-17 

f error function, 2-17, 2-36 

f flush function, 2-16 

fgets function, 2-20 

field width, 2-34 

file access, 

terminating, 2-10 

legal, 2-5 
file data, reading, 2-40 
file descriptor, 2-51 
file I/O, 1-5 
file pointer, 2-40 
file size, reducing, B-3 
file statements, 3-7 
file streams, manipulating, 2-17 
file.O, B-2 
file.C, B-l 
file.I, B-l 
file.IC, B-l 
file.S, B-2 
file.ST, B-l. 

filename, temporary, 2-30 
files, changing protection and 

ID, 2-9 
floating-point, 

conversion, 2-34 

routines, 2-2 
flushing stream files, 2-16 
fopen function, 2-18 
fopena function, 2-18 
fopenb function, 2-18 
for, 3-8 

form feed, 2-12 
formatting data, 2-33 
fprintf function, 2-33 
fputc function, 2-35 



fputs function, 2-37 
frame pointer, 1-2 
fread function, 2-20 
free function, 1-2, 2-8 
freopa function, 2-18 
freopb function, 2-18 
freopen function, 2-18 
fscanf function, 2-41 
fseek function, 2-21, 2-52 
ftell function, 2-21 
fwrite functions, 2-20 



getc function, 2-22, 2-52 
getchar function, 2-22 
getl function, 2-22 
getpass function, 2-24 
getpid function, 2-25 
gets function, 2-26 
getw function, 2-22 
GLOBAL, 3-4 
global data areas, 3-1 
global variable, 3-3 



H 



header file, 3-2 
heap management, 1-2 
heap space, allocating, 2-8 
heap extending, 2-7 
hex constant, 3-2 
hexadecimal ASCII, 2-34 

integer conversion, 2-42 
high bytes, reversing with low bytes, 
2-50 
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-I flag, B-l 
#include, B-l 
#include "file.h", 3-2 
I/O, 

redirection, 1-7 

stream, 2-18 

device, 1-5 

file, 1-5 

single-byte, 1-5 
if, 3-8 

illegal instruction trap, 2-44 
include files, nesting, 3-2 
indention technique, 3-8 
index function, 2-27 
initialization file, B-2 
initialized data, 1-1, 3-6 
input, 1-6 

format, 2-41 

stream, 2-52 
instruction trap, 2-3 
int, 

random number seed, 2-39 

variable length, 3-2 
intermediate code file, B-l 
intermodule communication, 

using procedure calls, 3-1 
isalnum(c), 2-12 
isalpha(c), 2-12 
isascii(c), 2-12 
isatty function, 2-28 
iscntrl(c), 2-12 
isdigit(c), 2-12 
islower(c), 2-12 
isprint(c), 2-12 
ispunct(c), 2-12 
isspace(c), 2-12 
isupper(c), 2-12 



JSR instruction, 1-2 



L 



L character, 2-34 

-L flag, B-2 

-L option, B-2 

language library, compatibility with 

UNIX V7, 2-1 
leading sign, 2-6 
leading spaces, 2-6 
line A trap, 2-44 
line F trap, 2-44 
line-feed, 1-6, 2-12, 2-41 
linkage editor, 1-2, B-2 
linker, B-l, B-2, B-3, B-4 
linker, invoking, 1-1 
listing device, 2-21 
literal matches, 2-42 
LO68, B-l, B-2 
load modules, B-3 
load time, reducing, B-3 
LOCAL, 3-4, 3-7 
local variable names, 3-3 
logical, 3-5 
LONG, 3-4 

long, 32-bit, 2-22, 2-34 
long masking constant, 3-5 
longjmp function, 2-43 
low bytes, reversing with high bytes, 

2-50 
lower-case, 2-2, 3-2, 3-3 
lseek function, 2-29 
LST:, 1-5 
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O 



macro, 2-4, 2-13, 2-22, 2-35 

macro definitions, 3-2 

maintenance costs, 3-1 

maintenance documentation, 3-8 

malloc function, 1-2, 2-8 

mandatory coding conventions, 3-2 

margin, 3-8 

masking, 3-5 

memory allocation, 2-15 

memory layouts of C programs, 1-1 

minus sign, 2-34 

mktemp function, 2-30 

MLOCAL, 3-4 

modular programs, 3-1 

module, 

layout, 3-7 

size, 3-1 
module-specific #define statements, 3-7 
movem.l instruction, 1-4 
multibyte binary variables, 3-2 
multicharacter constants, 3-5 



o character, 2-42 

o operator, 2-34 

-O file.68K, B-2 

object code, reducing size, 2-22 

octal, 

ASCII, 2-34, 2-42 

constant, 3-2 
open function, 2-10, 2-18, 2-31, 2-40 
open stream, 2-17, 2-41 
opena function, 2-31 
openb function, 2-3 1 
opening files, 2-31 
operations, 3-5 
OR, 3-5 
output, 1-6 

file, B-l 

left-adjusted, 2-34 

right-adjusted, 2-34 
overflow, detection and reporting, 2-6 



N 

nesting level, 3-8 
newline, 2-41 

character, 2-26, 2-37 

incompatibility, 2-37 
NO-OPS, 2-9 
nonlocal GOTO, 2-43 
null statement, 3-8 
null-terminated string, 2-34, 2-37 
concatenating, 2-46 



padding, blank or zero, 2-34 
parentheses, 3-2, 3-4 
parser, B-l 
password, 2-24 
PDP-11, 2-50 
percent sign, %, 2-33 
peripheral devices, 1-5 
perror function, 2-32, A-l 
pointer arithmetic, 3-5 
portability, 3-1 to 3-7 
precision field, 2-34 
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precision string, 2-34 
preprocessor, B-l 
primary memory, 2-20 
printf function, 2-33, 3-2, 3-5 
printing characters, 2-12 
privilege violation, 2-44 
procedure definitions, 3-7 
procedure header, 3-7 
process ID, false, 2-25 
punctuation characters, 2-12 
pushed-back characters, 2-52 
putc function, 2-35 
putchar function, 2-35 
putl function, 2-35 
puts function, 2-37 
putw function, 2-35 



qsort function, 2-38 
quick sort routine, 2-38 



R 



-R option, B-2 

rand function, 2-39 

random number generator, 2-39 

random numbers, retrieving, 2-39 

read errors, 2-23 

read function, 2-22, 2-40 

read pointer, 2-21 

readability, improving, 3-8 

realloc function, 2-8 

references, global, 3-7 

REG, 3-4 

registers, scratch, 1-4 

regular files, 1-6 

reloc utility, B-3 

relocatable files, B-2 



rewind function, 2-21 
rindex function, 2-27 
ROM, 3-6 
run-time start-up routine, B-2 



s character, 2-42 
s operator, 2-34 
-S option, B-2 
-S switch, B-4 
sample C module, C-l 
sbrk function, 1-2, 2-7, 2-14 
scanf function, 2-41 
screen editing, 3-8 
seed, 2-39 

setjmp function, 2-43 
sign-extending characters, 3-2 
signal function, 2-44 
signed characters, 2-47 
single-byte I/O, 1-5 
single-density disk system, B-3 
source file, B-l 
space, 2-12 

allocation for array, 2-8 
sprintf function, 2-33 
srand function, 2-39 
sscanf function, 2-41 
stack frame, 1-4 
stack use, 1-2 
stack-popping code, 1-4 
standard error file, 1-6 
standard type definitions, 3-3 
start-up file, B-2 
static data, 2-24 
static variables, 3-6 
stderr, 1-6 
stdin, 1-6 

<stdio.h> file, 1-6, 2-4, 2-22, 2-35 
stdout, 1-6 
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storage class, 3-7 
definitions, 3-3 
strcat function, 2-46 
strcmp function, 2-47 
strcpy function, 2-48 
stream, 

address, 2-16 

buffer, 2-29 

file, 2-21, 2-26 

output file, 2-15 
string, 

comparison, 2-47 

length, 2-47 

null-terminated, 2-24 

variables, 3-5 
strlen function, 2-49 
strncat function, 2-46 
strncpy function, 2-48 
strncmp function, 2-47 
stylistic rules in C programs, 3-1 
submit files, B-3 
subroutine calls, 1-4 
subtraction, 3-5 
suppressed assignments, 2-41 
swab function, 2-50 
swapping binary data, 2-50 
symbolic constants, 3-2 
symbolic names, A-l 
system, 

calls, 2-1 

error, 2-32 

include files, B-l 

traps, 2-1 
system-wide file, 3-2 



-T switch, B-4 
tab, 2-12, 2-41, 3-8 
tell function, 2-29 



temporary file, B-l 

terminal device, 2-51 

terminating current program, 2-3 

text, 3-6 

tilde, 2-12 

trace trap, 2-42 

trailing null, 2-37, 2-42 

transferring data, 2-54 

TRAPV instruction, 2-42 

ttyname function, 2-51 

type, 3-2 

type definitions, 3-3 

typedef, 3-3 



U 



u operator, 2-34 

-U option, B-2 

UBYTE, 3-4 

underline character, 1-4 

ungetc function, 2-52 

uninitialized data, 1-1, 3-6 

UNIX, 

compatibility, 2-9, 2-32, 2-37, 2-44 

versions 1 through 6, 2-29 

version 7, A-2 

with fopen, 2-19 

with getpid, 2-25 

with getchar, 2-23 
UNIX programs, with binary files, 

2-31 
unlink function, 2-53 
unsigned characters, 2-47 
unsigned int, 3-2 

upper bound of program, setting, 2-7 
upper-case, 2-2, 3-2, 3-3 
user control block, 1-5 
UWORD, 3-4 
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V 

variable, 3-7 
variable names, 

global, 3-3 

local, 3-3 

lower-case, 3-3 
variable type, 3-7 
VAX, 2-50 
vectors, sorting, 2-38 
VOID, 3-4 



W 

while, 3-8 

white space characters, 2-12 

WORD, 3-4 

16-bit, 2-35 

32-bit longword, 2-3 
word boundary, 2-8 
write function, 2-35, 2-54 
write pointer, 2-21 



X 

X characters, 2-30, 2-35, 2-42 
X operator, 2-34 



zero divide, 2-44 
zero padding, 2-34 
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Reader Comment Card 

We welcome your comments and suggestions. They help us provide you with better 
product documentation. 

Date 



1. What sections of this manual are especially helpful? 



2. What suggestions do you have for improving this manual? What information 
is missing or incomplete? Where are examples needed? 



3. Did you find errors in this manual? (Specify section and page number.) 
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CP/M-68K™ 
Operating System 
Release Notes 

Copyright© 1983 by Digital Research 

CP/M-68K and DDT are trademarks of Digital Research 

EXORmacs is a trademark of Motorola, Inc. 

Compiled February, 1983 



S-record Systems 

Either of • the two S-record versions of CP/M-68K™- included in 
this release can be combined with a user-supplied BIOS to obtain a 
working CP/M-68K operating system, as discussed in Section 6 of the 
CP/M-68K Operating System System Guide . In addition to the 
information given there, you need to know the size and entry points 
of the S-record systems. The two S-record systems are discussed 
separately in the following paragraphs. 

SR400.SYS resides in memory locations 400H to 5DFF. To patch 
it, place the 32-bit address of your BIOS' s _init entry point at 
memory locations 4F98 to 4F9B. Your BIOS can Warm Boot by jumping 
to 4F9C. 

SR128K.SYS resides in memory locations 15000H to 1A9FF. To 
patch it, place the 32-bit address of your BIOS's _init entry point 
at locations 19B98 to 19B9B. Your BIOS can Warm Boot by jumping to 
19B9C. 



Bugs 



• The CPM.SYS file on disk two of the distribution system was 
intended to work with a floppy disk EXORmacs system. It does 
not work at this time, but is to be modified to work at a 
future date. 

• AS68 does not operate properly when the disk it is using is 
full. 

• If you have trouble with AS68, you probably did not initialize 
it. See Section 5 of the CP/M-68K Operating System 
Programmer's Guide for more information. 

• When the program under test is specified on the CCP command 
line invoking DDT™ , DDT sets up an incorrect command tail. 
Use the I command in DDT to enter the command tail. 
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